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Chapter 1 


Introduction 


SunCGI (Sun Computer Graphics Interface) provides access to low-level graphics device func¬ 
tions without the restrictions, benefits, or overhead of higher-level graphics packages such as 
SunCore. SunCGI is useful for two-dimensional graphics programs which do not require seg¬ 
mentation or transformations. The absence of segmentation from SunCGI makes drawing 
diagrams faster and simpler, but does not provide automatic picture regeneration. SunCGI pro¬ 
grams are usually smaller and more efficient than SunCore programs with similar functionality. 
In addition, SunCGI programs will run on all of Sun’s devices without explicitly specifying the 
device at compile time. Furthermore, SunCGI provides output primitives (for example, circles), 
attributes (for example, sophisticated pattern filling), and input primitives which are not offered 
by SunCore. 

SunCGI is Sun Microsystem’s interpretation of the March, 1984 working draft of the ANSI X3H3 
committee which is commissioned with designing the CGI standard^. The CGI standard is 
currently under development, and therefore, CGI has not been accepted by the X3H3 committee, 
ANSI, or the computer graphics community. Furthermore, only certain models within the CGI 
proposed standard are supported by SunCGI. Specifically SunCGI implements input option 
sets 1, 2, 3, 4, and 6 and output option sets 1 through 6 of the CGI standard. Furthermore, the 
user should be aware that CGI does not support three-dimensional output primitives. 

SunCGI does provides output primitives, attribute selection, and input device management, at a 
level which is close to the actual device driver; thus affording speed and flexibility not offered by 
higher-level graphics packages such as SunCore. SunCGI provides output primitives which 
are not provided by any of the other Sun graphics packages: for example disjoint polygons, cir¬ 
cles, ellipses, and cell arrays (which can be thought of as scaled and transformed pixel arrays). 
CGI also provides a larger vocabulary of attributes than SunCore. SunCGI also provides facili¬ 
ties for explicitly binding virtual input devices to physical input devices as well as explicit 
management of an event queue. 


1.1. Notations Used in this Manual 

Within the text of this manual, a typewriter font is used to represent function names and 
types. For example, append_text is the name of a function; Cint is the name of a type. 
The formal definitions of functions and arguments are printed in the typewriter font so 
that they resemble code as typed at a terminal. 

1 Both the CGI standard and Sun’s interpretation of it are subject to change. 
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Italic font is used to indicate an internal state of SunCGI. Internal states of SunCGI are not 
explicitly enumerated, but their definition should be obvious from their names (for example, 
current font). Internal states are distinguishable from function arguments in that they do not 
use the underscore (_) character. 

Italics are also used in the conventional manner (that is, to accentuate important words and 
phrases). Boldface is used for the names of Sun software packages such as SunCGI and Sun- 
Core. 

In examples of what a user types at a terminal, a bold typewriter font is used to 
represent what the user types, and the typewriter font represents what the software 
displays in response. 


1.2. Using SunCGI 

To link SunCGI with your application program, put the following line in your Makefile: 

cc testl.o -Icgi -Isunwindow -Ipixrect -Im 

where testl.o is the name of the application program. Similarly, if your application program uses 
other libraries, they must also be included in the Makefile line. 

SunCGI uses a variety of structures and enumerated types. These types are defined in Appen¬ 
dix C. You should include the files <cgitypes.h>, and <cgiconstants.h> to provide the neces¬ 
sary type definitions and constants for your application program. 

All SunCGI functions can be called by one of two names: the expanded name or the C- 
language binding name. The expanded name is the first name provided in the function descrip¬ 
tion section, whereas the C-language binding name is specified in parenthesis. You must include 
the file <cgicbind.h> in your application program if you want to use the C-language binding 
name. The C-language binding names are an attempt to anticipate the C-language binding of 
CGI. However, no C-language binding has been included in the CGI standard, and the SunCGI 
binding is inspired by the C-language binding of GKS. 

As a final note, do not name any user-defined function or variable starting with the letters _cgi 
because doing so may disrupt the internal workings of SunCGI. 

FORTRAN programmers can access SunCGI functions by using the include file in cgidefs77 .h 
and using the /usr/lib/libcgi77.a library to link with. Details of the FORTRAN interface to 
SunCGI are provided in appendix G. 


1.3. Overview of SunCGI 

This section provides an overview of the substance of the SunCGI manual. The four major sec¬ 
tions of the manual (which correspond to chapters) are: 

1) view surface initialization and termination (control), 

2) output primitives, 

3) attributes, and 

4) input. 

The overview of these chapters contains a brief introduction to the basic concepts of CGL The 
appendices at the end of this manual provide quick reference tables and descriptions of the inter¬ 
faces between SunCGI and 


1-2 


Revision A of 15 May 1985 




SunCGI Reference Manual 


Introduction 


1) Pixwins and 

2) FORTRAN. 

1.3.1. Control (Initialization and Termination) 

The chapter on control describes functions for 

1) initializing and terminating the entire SunCGI package and individual view surfaces, 

2) defining the coordinate systems, 

3) interface negotiation, and 

4) signal trapping. 

The first section of the control chapter describes functions for opening and closing view surfaces 
(which are either windows or screens). SunCGI provides facilities for writing primitives to mul¬ 
tiple view surfaces. Output primitives can be written to a selected subset of the open view sur¬ 
faces by using the activate and deactivate commands (which turn a view surface on or off 
without closing the view surface). The functions discussed in the control chapter also define the 
range of normalized device coordinates (VDC Space) and device coordinates (screen space). The 
coordinates of most SunCGI functions are expressed in terms of VDC Space. The limits of both 
VDC Space and screen space can be defined by the application program. 

If you are attempting to run an application program developed on another vendor’s version of 
CGI, negotiation functions are provided which describe the capabilities of SunCGI. The applica¬ 
tion program can use the information obtained by using the negotiation functions to call 
appropriate functions in SunCGI to make the application program run correctly. Finally, the 
control chapter describes SunCGI’s option for trapping SIGWINCH signals (generated by manipu¬ 
lating the window which the application program is using). 


1.3.2. Output 

SunCGI provides functions for drawing geometrical output primitives (for example, polygons, 
circles, and ellipses) as well as functions for performing raster operations. The coordinates of 
output primitives are specified in VDC Space (with the exception of some raster functions). 
Geometrical output primitives include rectangles, pol 3 Tnarkers circular and elliptical arcs in 
addition to those mentioned in the previous sentence. Geometrical output primitives are affected 
by attributes described in the following chapter (such as fill style and line width). All output 
primitives are affected by the drawing mode which determines how an output primitives is 
affected by pixels which have been previously drawn on the screen. 


1.3.3. Attributes 

Attributes functions control the appearance of output primitives. Attributes can be set individu¬ 
ally, or in groups which are called bundles. The use of most attributes is fairly straightforward; 
however, the options available for filling geometrical output primitives requires a word of expla¬ 
nation. Geometrical output primitives can be filled with textures called hatches or patterns. 
Hatches are simply arrays of color values with each element of the array corresponding to a 
pixel. Patterns are arrays of color values which can be scaled and translated. 
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1.3.4- Input 

SunCGI offers a standard interface for receiving input from the mouse and the keyboard. The 
CGI input model is based on the concept of logical input devices such as LOCATORS, 
VALUATORS,and STROKES. Logical input devices are bound to physical devices (such as mouse 
buttons) called triggers. Triggers may be associated with logical input devices by the application 
program. Each logical input device has an associated measure (for example, the measure of a 
LOCATOR device is the mouse position on the screen). Each logical input device also has a state 
which determines how a device handles input. Each logical input device can be in one of five 
states: 

1) RELEASED (uninitialized), 

2) NO_EJVENTS (initialized but unable to receive input), 

3) REQUEST_EVENT (wait for one event), 

4) RESPOND_EADNT (report one event asynchronously), and 

5) QUEUE_EVENT (put each event at the end of the event gueue). 

1.3.5. Programming Tips 

For novice C-language users, the syntax of SunCGI may pose some initial difficulties. When a 
pointer is specified as an argument to a SunCGI function, SunCGI usually expects space to be 
allocated by the application program and the function argument to be preceded by an amper¬ 
sand (<&). SunCGI uses many enumerated types. These types are printed by the printf func¬ 
tion as integers. If you want to print out these values in English, you should use the enumerated 
types as indices into a character array which contains appropriate English equivalents of the 
enumerated types. Finally, if you are a novice programmer, begin by copying the example pro¬ 
gram in the example program appendix and develop your application program from this example. 
Further help can be obtained by referring to the tables at the end of the appendix specifying 
error messages. These tables list commonly encountered problems and how to solve them. 


1.3.6. Appendices 

The first five appendices are provided as an informational reference which may make SunCGI 
easier to understand. This information will probably be particularly useful to novice users. The 
last two appendices describe the interfaces: 

1. between SunCGI and Pixwins (the SunWindow System) and 

2. betweenSunCGI and the FORTRAN programming language. 


l.S.6.1. Reference Appendices 

The first appendix explains the difference between SunCGI and SunCore. The next appendix 
lists the ANSI CGI standard functions which are not implemented by SunCGI and the SunCGI 
functions which are not part of the ANSI CGI standard. The third appendix provides the type 
definitions used by the SunCGI functions. The fourth appendix lists the error messages and 
possible strategies for eliminating them. This appendix also lists possible causes of simple run¬ 
time errors. Finally, the fifth appendix describes a sample program. 
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1,3.6.2. Detcription of Interfaces to SunCGI 

The final two appendices describe the interfaces between SunCGI and other Sun software 
packages: Pbcwins and FORTRAN. The first of the two interface appendices explains how to call 
SunCGI from application programs written on top of Pixwins, This interface allows SunCGI 
to write output primitives in different pixwins using different attributes. This interface is useful 
for application programs which wish to control different areas of the view surface independently. 
The final appendix describes the interface to the FORTRAN programming language. The behavior 
of each SunCGI function is the same in both C and FORTRAN. 


1.4. References 

1) ANSI X3H3 Technical Committee, 1984, ‘Graphics Kernel System dpANS’, ACM SIG- 
GRAPH, February 1984, ACM, New York. 

2) ANSI X3H3 Technical Committee, 1984, ‘Virtual Device Interface dpANS’, X3H3 84/45, 
March 1984, ANSI, New York. 
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Chapter 2 


Initializing (and Terminating) SunCGI 


2.1. View Surface Selection And Initialization 

No functions for initializing and terminating devices are provided in the current CGI standard. 
Therefore, six nonstandard functions open_cgi, close_cgi, open_vws, close_vws, 
activate., vws, and deactivate_vws are included in SunCGI. open_cgi and 
close_cgi initialize and terminate the operation of the SunCGI package. A view surface is 
initialized by calling open_vws. SunCGI is capable of handling more than one view surface at 
once. However, output primitives are not displayed unless a view surface is activated. 

A view surface is automatically activated when it is opened. However, a view surface can be 
deactivated (with the deactivate_vws function) when the output stream is not intended to 
appear on all view surfaces. Subsequent calls to SunCGI output functions will not apply to 
deactivated view surfaces^ until activate^ws is called again (see the following example). 


2 However, inputs can be received on deactivated view surfaces. 


Revision A of 15 May 1985 


2-1 





Initializing (and Terminating) SunCGI 


SunCGI Reference Manual 


main () 

{ 

Cvwsurf devicel,device2; /* declarations */ 

Clnt naiael,name2; 

Ccoor bot,top,center; 

Cint radius; 

/* values of arguments are assiimed to be set by you */ 


open_cgi(); /* start cgi */ 

NORMAL_VWSURF (devicel, PIXWINDD) ; /* black-and-white view surface */ 
open_vws{&namel,&devlcel); /♦ open device number 1 */ 

NORMAL_VWSURF (device2, CGIDD) ; /* color view surface */ 


open_vws{&name2,&device2); /* 
rectangle (&bot,Stop); /* 
deactivate_vws(name2); /* 
circle(ficenter,radius); /* 
activate_vws(name2); /* 
circle(ficenter,2*radius); /* 
close_vws(namel); /* 
close_vws(name2); /* 
close_cgi(); /* 

} 


open device number 2 */ 

draw a rectangle on both devices */ 

deactivate device number 2 */ 

draw a circle on device no. 1 only */ 

activate device number 2 */ 

draw a circle on both devices */ 

close device number 1 */ 

close device number 2 */ 

close cgi */ 


t.Ll. open_cgi (Copencgi^ 

Cerror open_cgi() 

open_cgi initializes the state of SunCGI to CGOP (CGi OPen). open_cgi does not initial¬ 
ize input devices but does initialize the event queue. No other CGI functions can be used without 
generating an error if open_cgi has not been called. 

ERRORS: 

1 ENOTCGCL CGI not in proper state; CGI shall be in state CGCL. 

Errors are reported in SunCGI by setting the return value of the function to a nonzero result 
and echoing an error message and number on the terminal. However, error trapping can be con¬ 
trolled by the set_error_warning_mask function. An explanation of each error message 
(and suggestions for how to eliminate them) is presented in Appendix D. 
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Table 2-1: SunCGI Default States 


State 

Value 

Range of VDC Space 

(0—32767 in both X and Y directions) 

Clip Indicator 

ON 

Clip Rectangle 

(Range of VDC Space) 

Error Warning Mask 

INTERRUPT 

Input Devices 

(Uninitialized) 

Input Queue 

EMPTY 

Trigger Associations 

(Defaults specific values listed in Table 5-4) 

Echo Modes 

(Device specific values listed in Table 5-5) 


Some of the entries discussed in Table 2-1 may be unfamiliar to you at this time. However, all of 
these concepts are explained in the course of this chapter. Further, each of these concepts are 
referenced in the index. 


2.1.2. open„vws fCopenvwsj 


Cerror open_vws(name,devdd) 

Cint *name; /* name assigned to cgi view surface */ 

Cvwsurf *devdd; /* view surface descriptor */ 

open_vws initializes a view surface. The list of available view surfaces is described below in 
Table 2-2. open_vws initializes the attributes to their default values (listed in Table 2-3). The 
returned argument name is the identifier which is used to refer this view surface in other 
SunCGI functions. If you want to reinitialize the state of the view surface without reopening it, 
you should use the hard_reset function. 

More than one view surface can be open at one time. Output primitives are displayed on all 
active view surfaces (view surfaces must be opened before they are activated). However, input 
is only echoed on the view surface which is pointed to by the mouse. You must set the view sur¬ 
face type by assigning the dd element of the devdd argument to the name of the appropriate dev¬ 
ice driver as in this example*: 

Cvwsurf device; 

NORMAL_VWSURF(device. BW2DD); /* black-and-white view surface */ 
open_vws(&name,&device); 


* Notice that when SunCGI specifies a pointer it usually requires that the argument is prefaced by an & 
character when the argument is actually used. 
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The NORMAL_VWSURF macro initializes the dd element of the Cvwsurf structure and guarantees 
that the view surface will be opened in the normal fashion. However, if you want to open a win¬ 
dow with some nonstandard parameters, or open a second window from a graphics tool you 
should read the following paragraphs. If you want to use an existing pixwin then you should skip 
the following paragraphs and read Appendix F instead. 

If the view surface of the specified type has been previously initialized and the type of view sur¬ 
face is a window (PIXWINDD or CGPIXWINDD), a CGI tool (a window with the name CGI Tool) 
is opened. You may also define other characteristics of the view surface by setting the other ele¬ 
ments of the of the devdd argument (which is of type Cvwsurf). 

typedef struct •{ 

char screenname[DEVNAMESIZE]; /* 
char windowname[DEVNAMESIZE]; /* 
int windowfd; /* 

int retained; /* 

int dd; /* 

int cmapsize; /* 

char cmapname[DEVNAMESIZE]; /* 

int flags; /* 

char * *ptr; /* 

} Cvwsurf; 

The elements tcreenname and windowname specify alternate screens (for example, fdevjcgoneO) 
or alternate window (for example, fdevfwinlO). If these elements are left blank, the current 
screen and the current window are used, unless the dd field implicitly specifies a device (for 
example CGlDD). The element windowfd is the window file descriptor for the current device. 
The current implementation of SunCGI ignores this element. 

If the element retained is nonzero, then the view surface created by open_vws has a retained 
window associated with it (that is, if the window is covered-up by another window and then 
revealed, the picture present before the window was covered-up will be redisplayed. 

By default the window created by open_vws is non-retained. That is, if the window is 
covered-up and then revealed the covered-portion will be redisplayed as white. However, draw¬ 
ing in non-retained windows is twice as fast as drawing in retained windows, so the choice of 
which type of view surface to open should be carefully considered. 

The dd element specifies the view surface type. The cmaptize and the cmapname elements 
determine the size and the name of the colormap. No colormap i» enabled for black-and-white 
devicet. The colormap determines the mapping between color indices and red, green, and blue 
values. If the colormap specified by the cmapname element of the devdd argument is the same as 
a colormap segment which already exists, then the colormap segment is shared. Refer to the 
Programmera* Reference Manual for Sun Windowa for more information about colormaps. 

When the flaga element is nonzero, no attempt is made to take over the current graphics 
subwindow (if one exists). If this flag is set or the graphics subwindow has already been taken 
over by SunCGI, then a CGI Tool (a window with the name CGI Tool) is created. The view sur¬ 
face descriptor returned in name refers to the CGI Tool. The ptr element specifies the size and 
placement of the CGI Tool. Ptr is a pointer to a nine element array of characters. Each element 
of the array should be filled with an integer. The first two elements specify the x- and y- 
coordinates of the upper left-hand corner of the CGI Tool. The third and fourth elements specify 


physical screen */ 
window */ 

window file descriptor */ 

retained flag */ 

device */ 

color map size */ 

color map name */ 

new flag */ 

CGI tool descriptor */ 


2-4 


Revision A of 15 May 1985 










SunCGI Reference Manual 


Initializing (and Terminating) SunCGI 


the width and height of the CGI Tool. The fifth through eighth elements specify the position and 
size of the iconic form of the CGI Tool. If the ninth element is nonzero, the tool is displayed in 
its iconic form. 


ERRORS: 

5 ENOTOPOP 

11 ENOWSTYP 

12 EVSISOPN 


CGI not in proper state CGI shall be either in state CGOP, VSOP, or 
VSAC. 

Specified view surface type does not exist. 

Specified view surface is open. 


Table 2-2; Available View Surfaces 


Surface Name 

Description 

BWIDD 

for the Sun-1 monochrome display 

BW2DD 

for the Sun-2 monochrome display 

CGIDD 

for the Sun-1 color display 

CG2DD 

for the Sun-2 color display 

PIXWINDD 

for windows on the Sun-1 monochrome display 

CGPIXWINDD 

for windows on color display 


Table 2-3: View Surface Default States 


State 

Value 

View Surface 

(Cleared) 

Device Viewport 

(Total Screen) 


2.1.3. activate_vws (Cactws) 

Cerror activate_vws(name) 

Cint name; /* view surface name */ 

activate_vws activates the view surface specified by name. Future SunCGI calls affect this 
view surface. Nothing ta displayed on o view surface unless that view surface is active. Note 
that activating a view surface may reset the state of SunCGI. 

ERRORS: 

5 ENOTOPOP CGI not in proper state CGI shall be either in state CGOP, VSOP, or 
VSAC. 

10 EVSIDINV Specified view surface name is invalid. 


Revision A of 15 May 1985 


2-5 







Initializing (and Terminating) SunCGI 


SunCGI Reference Manual 


13 EVSNOTOP Specified view surface not open. 

14 EVSISACT Specified view surface is active. 

2 . 1 . 4 ^ deactivate_vws (Gdeactvws^ 

Cerror deactivato_vws(name) 

Cint name; /* view surface name */ 

deactivate_vws prevents calls to SunCGI functions from having an effect on this view sur¬ 
face. The view surface may be reactivated at a later time without having to be reopened. Note 
that activating a view surface may reset the state of SunCGI. 


ERRORS: 


4 

ENOTVSAC 

CGI not in proper state: CG! shall be in state VSAC. 

10 

EVSIDINV 

Specified view surface name is invalid. 

13 

EVSNOTOP 

Specified view surface not open. 

15 

EVSNTACT 

Specified view surface is not active. 

2.1.5. 

close_vws 

('Cclosevws^ 


Cerror close_vws(name) 

Cint name; /* view surface name */ 

close_vws terminates a view surface. Future SunCGI calls have no effect on this view sur¬ 
face. The view surface cannot be reactivated without being reopened. 

ERRORS: 

5 ENOTOPOP CGI not in proper state CGI shall be either in state CGOP, VSOP, or 
VSAC. 

10 EVSIDINV Specified view surface name is invalid. 

13 EVSNOTOP Specified view surface not open. 


2.1.6. close_cgi CCclosecgij 


Cerror close_cgi() 


close_cgi terminates all open view surfaces, and restores the state of the window system to 
the state that it was in before SunCGI was opened. Future SunCGI calls will have no effect 
and will generate errors. 
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It is recommended that you include a call to close_cgi in the“exit routines of your applica¬ 
tion program to guarantee leaving the window system and SunCGI in a stable state. 


ERRORS: 

5 ENOTOPOP CGI not in proper state CGI shall be either in state CGOP, VSOP, or 
VSAC. 


2,2. Interface Negotiation 

CGI is intended to support a ‘negotiated device interface’ which permits programs written on a 
specific type of hardware to run on other machines. SunCGI only allows inquiry of most of the 
settable modes.^ For example the user may want to find out which types of input devices are 
supported. However, functions for setting color precision, coordinate type, specification mode, 
and color specification are not provided because SunCGI only supports one type of color preci¬ 
sion (8-bit), coordinate type (integers), and color specification (indexed). The width and size 
specification modes are settable, but the functions which set them are described in the chapter 
on attributes. However, the inquiry negotiation functions are supported so that an application 
program written for a CGI on another manufacturers’ workstation can find out whether the 
SunCGI is capable of running that application. 


£. 2 . 1 . inquire_device_identification (Cqdevidj 

Cerror inquire_device_identlflcation (name,devld) 
Clnt name; /* device name */ 

Cchar *devld; /* Workstation type */ 


inquire_device_identification reports which type of Sun Workstation view surface 
name is associated with. The argument devid may be set to one of the six Sun Workstation 
types: BWlDD, BW2DD, CGIDD, CGSDD, PIXWINDD, or CGPIXWINDD. The inclusion of 
the name argument deviates from the ANSI standard, but is necessary so that the characteristics 
of individual view surfaces may be inquired. 


ERRORS: 


5 

ENOTOPOP 

10 

EVSIDINV 

13 

EVSNOTOP 


CGI not in proper state CGI shall be either in state CGOP, VSOP, or 
VSAC. 

Specified view surface name is invalid. 

Specified view surface not open. 


* The functions which are not supported by SunCGI are classified as non-required by the March 1884 
ANSI oca standard. 
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S.2.3. inquire_device_class (Gqdevclass^ 

Cerror inquire_device_class(output,input) 

Cint *output,*input; /* output and input abilities */ 


inquire_d©vice_class describes the capabilities of Sun Workstations in terms of the CGI 
functions they support^. Each of the two returned values reports the number of functions of 
each of the two classes which are supported in SunCGI. These numbers (the values of input and 
output) are used to make more detailed inquiries by using functions such as 
inquire_output_capabilities. 

ERRORS; 

5 ENOTOPOP CGI not in proper state CGI shall be either in state CGOP, VSOP, or 
VSAC. 


inquire_physical_coordinate_system (Cqphyscsys^ 


Cerror inquire_physical_coordinato_system 

(name,xbase,ybase,xext,yext,xunits,yunits) 

Cint name; /* name assigned to cgi view surface */ 

Cint *xbase,*ybaso; /* base coordinates */ 

Cint *xext,*y©xt; /* number of pixels in each direction */ 
Cfloat ‘xunits,*yunits; /* number of pixels per mm. •/ 


inquire_coordinate_system reports the physical dimensions of the coordinate system of 
view surface name in pixels and millimeters. The lnquire_coordinate_system function is 
provided to permit the drawing of objects of a known physical size. 
inquire_coordinate_system is also provided to assist in the computation of parameters for 
the device_viewport function. Xext and yext describe the maximum extent of the window 
in which the application program is run (The window may or may not cover the entire screen.) 
The number of pixels per millimeter is always set to 0 because the actual screen size of device 
varies between individual monitors. If you want to compute the actual size of the screen, you 
may obtain the number of pixels in the z and y directions from the monitor specifications and 
perform the division in your application program. 

ERRORS: 

5 ENOTOPOP CGI not in proper state CGI shall be either in state CGOP, VSOP, or 
VSAC. 


10 EVSIDINV Specified view surface name is invalid. 

13 EVSNOTOP Specified view surface not open. 


^ The output argument does not include the non-standard CGI functions. 
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2.S.4. inquire_output_function_set (Cqoutfunsety 

Cerror inquire_output_function_set (level,support) 

Cint level; /* level of output */ 

Csuptype *support /* amount of support */ 

inquire_output_function_set reports the extent to which each level of the output por¬ 
tion of the ANSI CGI standard is supported. 

typedef enum { 

NONE, 

REQUIRED_FUNCTIONS_ONLY, 

SOME_NON_REQUIRED_EUNCTIONS, 

ALL_NON_REQUIRED_FUNCTIONS 
)• Vsuptype; 

The standard requires that the level argument be an enumerated type; however, for reasons of 
simplicity only the level number is used by SunCGI. Levels 1-6 are supported completely (that 
is, both required and non-required functions are implemented. Level 7 is not supported at all. 
Refer to the ANSI standard for the precise definition of each level. 

ERRORS: 

5 ENOTOPOP CGI not in proper state CGI shall be either in state CGOP, VSOP, or 
VSAC. 


2.2.5. inquire_vdc_type (Cqvdctype,? 

Cerror inquiro_vdc_type(type) 

Cvdctype ‘type; /* type of vdc space */ 


inquire_vdc_type reports the type of coordinates used by SunCGI in the returned argu¬ 
ment type. 


typedef enum ■{ 

INTEGER, 

REAL, 

BOTH 

J Cvdctype; 

Type is always set to INTEGER (32-bit). Use SunCore if you want to use a system with coordi¬ 
nate space expressed in real numbers. 

ERRORS: 

5 ENOTOPOP CGI not in proper state CGI shall be either in state CGOP, VSOP, or 
VSAC. 
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2.2.6. inquire_output:_capabilities ^Cqoutcap^ 

Cerror inquire_output_capabilities (first,num,list) 

Cint first,num; /* first and number elements 

of list to be returned */ 

Cchar *list[]; /* returned list */ 

inquire_output_capabilities lists the output functions in the returned argument Hat. 
The range of the first and num arguments is determined by the returned argument output from 
the inquire_device_class function. 

ERRORS: 

5 ENOTOPOP CGI not in proper state CGI shall be either in state CGOP, VSOP, or 
VSAC. 

16 EINQLTL Inquiry arguments are longer than list. 


2.2.7. Input CapahiUty Inquiries 

Input devices have a separate class of negotiation functions. Input capability inquiries report 
qualitative abilities as well as quantitative abilities of input devices. The 
inquiro_input_capabili'ties function reports which devices and overall features are sup¬ 
ported by SunCGI. The remaining functions report the capabilities of individual devices or 
features. 


Input devices are virtual devices which must be associated with physical triggers (such as 
mouse buttons). Initializing an input device defines the measure used by a device, for example 
initializing a LOCATOR device defines the measure as x,y coordinates. In addition to being 
associated with a trigger, each device has selectable screen echoing capabilities. Association and 
echoing capabilities for each input device are reported by the functions described in this section. 


2,2.7.1. inquirG_input_capabilities ftqinpcaps^ 


Cerror inquire_input_capabilities (valid,table) 

Clogical ‘valid; /* device state */ 

Ccgidesctab ‘table; /‘ CGI input description table ‘/ 

inquire_input_capabilities reports the total number of input devices of each class that 
are supported. The argument valid returns the value L_TRUB if SunCGI is initialized, and 
L_FALSE otherwise. If valid is set to L_TRUE, the elements of table are set to the quantity and 
quality of inputs supported by the specific view surface. All Sun Workstation# support input 
at the same level. 
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typedef struct { 

Cint numloc; 

Cint nximval; 

Cint numstrk; 

Cint numchoice; 

Cint nxunstr; 

Cint numtrig; 

Csuptype event_queue; 

Csuptype asynch; 

Csuptype coord_map; 

Csuptype echo; 

Csuptype tracking; 

Csuptype pronpt; 

Csuptype acknowledgement; 

Csuptype trigger_manipulatlon; 

} Ccgidesctab; 

Elements of type Cint report how many of each type device is supported, as well as how many 
types of triggers are supported. Elements of type Csuptype report how many of the functions of 
each class are supported. All functions except the tracking functions are fully supported. 

ERRORS; 

5 ENOTOPOP CGI not in proper state CGI shall be either in state CGOP, VSOP, or 
VSAC. 


2.2.7.8. inquire_lid_capabilities (Gqlldcaps^ 


Cerror inquire_lid_capabilitios (devclass,devnum,valid,table) 
Cdevoff devclass; 

Cint devnum; /* device type, device number */ 

Clogical ‘valid; /* device supported at all ‘/ 
Cliddescript ‘table; /* table of descriptors */ 


inquire_input_device_capabilities describes the capabilities of a specific input device 
(hereafter, specified device). The input arguments devclass and devnum refer to a specific dev¬ 
ice type and number. The argument valid reports whether CGI is initialized. 

typedef struct •{ 

Clogical sanple; 

Cchangetype change; 

Cint numassoc; 

Cint ‘trigassoc; 

Clogical pronpt; 

Clogical acknowledgement; 

Cechoav ‘echo; 

Cchar ‘classdep; 

Cstatelist state; 

} Cliddescript; 
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The elements of table which are of type Clogteal indicate whether an ability is present in a 
specified logical input device. The change element reports whether associations are changeable 
at all (all input devices except string are not changeable). The numasaoc and trigasaoc elements 
of table report how many and which triggers are associated with the specified logical input dev¬ 
ice. The echo argument describes which echo types are supported (see the chapter on input for 
a list of echo types®). The clasadep argument provides class dependent information in character 
form (the type of information is given in Table 2-3). If more than one piece of class dependent 
information is returned, then the pieces of information are separated by commas. The state 
argument reports the initial state of the specified device. See the inquire_state_list func¬ 
tion. 


Table 2-4: Class Dependent Information 


Device Class 

Information 

Possible Values 

IC_XOCATOR 

Coordinate Mapping 

(Yes, No,Partial) 


Native Range 

(xmin,xmax,ymin ,ymax) 

IC.VALUATOR 

Set Valuator Range 

(yes/no) 

IC_STROKE 

Time Increment Settable 

(yes/no) 


Minimum Distance 

(yes/no) 

IC.CHOICE 

Range 

(min/max) 

IC_STRING 

None 

None 


ERRORS: 

5 ENOTOPOP CGI not in proper state CGI shall be either in state CGOP, VSOP, or 
VSAC. 


2.2.7.S. inquire_-trigger_capabilities (bqftrigcaps) 

Cerror inquiro_trigger_capabilities(trigger.valid,tdis) 

Cint trigger; /* trigger nxunber */ 

Clogical ‘valid; /* trigger supported at all */ 

Ctrigdis *tdis; /* trigger description table */ 

inquire_trigger_capabilities describes how a particular trigger can be associated. The 
argument valid reports whether the device supports input at all. 


^ Note that lnqulro_lid_capabllltla8 returns &n enumerated type whereas track_on accepts 
integers. Therefore these values may be different. 
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typedef struct { 

Cchangetype change; 

Cassoclld *numassoc; 

Cint maxassoc; 

Cpromstate pron^t; 

Cackstate acknowledgement; 

Cchar ‘name; 

Cchar ‘description; 

} Ctrigdis; 

The change element of tdie reports whether the specified trigger can he associated with a logical 
input device. The ntimasaoc and trigaetoc elements of td{» report how many and which logical 
input devices can be associated with trigger. The maxassoc element reports the maximum 
number of devices that can be associated with a particular trigger. The prompt and ack¬ 
nowledgement elements report the ability of the trigger to support these abilities. SunCGI does 
not support either prompt or acknowledgement for any input device. The name element is sim¬ 
ply a character form of the trigger name (for example, LEFT MOUSE BUTTON). The description 
element is never filled and is included for standards compatibility. 

ERRORS: 

5 ENOTOPOP CGI not in proper state CGI shall be either in state CGOP, VSOP, or 
VSAC. 

88 EINTRNEX Trigger does not exist. 


2.3. View Surface Control 

The functions described in this section 

1. define the range of world and device coordinates, 

2. control clipping, and 

3. reset selected aspects of the view surface and the internal state of SunCGI. 

2.S.I. Coordinate Definition 

Most functions in SunCGI express coordinates in VDC Space (Virtual Device Coordinate Space). 
In conventional computer graphics terms, VDC Space corresponds to world coordinate space. 
The mapping between VDC Space and screen space is determined by the physical size of the 
screen in pixels. Screen space is set by default to the entire size of the screen or the graphics 
window depending on the device type. The mapping from VDC Space to screen space is always 
isotropic (the shape of the rectangle defining screen space is the same shape as VDC Space). 
Therefore, VDC Space defines the shape of the active view surface. The portion of screen space 
which does not correspond to VDC Space is ignored. The aspect ratio (the ratio between the 
height and width) is therefore, defined by VDC Space and not screen space. 
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2.S.I.I. vdc_extent /'Cvdcextf 

o 

Cerror vdc_extent (cl, c2) 

Ccoor *cl, *c2; /‘bottom left-hand and top right-hand 

corner of VDC space */ 

vdc_extent defines the limits of VDC Space. The range of the coordinates must be between 
—32767 and 32767 (or an error is generated). VDC Space can be set by you, but it ranges from 0 
to 32767 in both the X and the Y directions by default. Resetting VDC Space impacts the display 
of output primitives on all view surfaces. 

Resetting the limits of VDC Space automatically redefines the clipping rectangle to the new 
limits of VDC Space, regardless of the value of the dip indicator. 

Changing the mapping from screen space to VDC Space allows you to translate (move) or scale 
(zoom in/zoom out) the output primitives. However, no rotation functions are provided by 
SunCGI, and therefore, must be built by you. The code fragment below translates and zooms 
in on a rectangle: 


o 
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#include <cgid 9 fs.h> 
main () 

-c 

Cvwsurf device; 

Cint name; 

Ccoor upper,1over; 

Cint xl,yl,xu,yu; 

Ccoor dvl.dv2; 

device.dd = PIXWINDD; /* turn on a pixwin */ 
open_cgi (); 

open_vws(&name,^device); 

actlvate_viow_surface(name); 

lower.x=30; /* coordinates of rectangle */ 

lower.y=30; 

upper.x=70; 

upper.y=70; 

dvl.x = 0; 

dvl.y = O; 

dv2.x = 200; 

dv2.y = 200; 

vdG_extent (&dvl,&dv2); 

rectangle(&upper,Slower); /* draw initial rectangle */ 

sleep(4); 

dvl.X = O; 

dvl.y =0; 

dv2.x = 100; 

dv2.y = 100; 

vdc_extent(&dvl.&dv2); /* center rectangle */ 

rectangle(Supper , Slower); 

sleep (4) ; 

dvl.x = 20; 

dvl.y = 20; 

dv2.x = 80; 

dv2.y = 80; 

vdc_extent(Sdvl,Sdv2); /* enlarge rectangle */ 

rectangle(Supper,Slower); 
sleep (4); 

close_view_surface(name); 
close_cgi(); 

> 


ERRORS: 


5 

ENOTOPOP 

20 

EBADRCTD 

24 

EVDCSDIL 


CGI not in proper state CGI shall be either in state CGOP, VSOP, or 
VSAC. 

Rectangle definition is invalid. 

VDC space definition is illegal. 
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2.3.1.8. device_viewport (Cdevvpt.) 

Cerror devico_viewport(name,cl,c2) 

Cint name; /* name assigned to cgi view surface */ 

Ccoor *cl,*c2; /* bottom left-hand and top right-hand corner of view 

surface to map device onto (expressed in pixels) */ 

device_viewport redefines the limits of screen space. If the new limits are not less than or 
equal to the size of the current screen or window size, an error is returned. Although 


device_viewport 
are unused. 

does not redefine the aspect ratio, it may redefine which areas of the screen 

ERRORS: 


5 

ENOTOPOP 

CGI not in proper state CGI shall be either in state CGOP, VSOP, or 
VSAC. 

10 

EVSIDINV 

Specified view surface name is invalid. 

13 

EVSNOTOP 

Specified view surface not open. 

20 

EBADRCTD 

Rectangle definition is invalid. 

21 

EBDVIEWP 

Viewport is not within Device Coordinates. 

2.3.2. 

Clipping 



For some application programs, it is desirable to have clipping explicitly within the viewport, 
while other applications may seek to increase efficiency by not checking if the coordinates are 
within the bounds of the clipping area. 

All SunCGI application programs will run faster if clipping is turned off. However, clipping is 
turned on by default to prevent SunCGI from drawing outside of the bounds of the window. 

The clipping area is set by the clip_rect:angle function. 


2.3.8.1. clip_indica1:or (fcclipind^ 


Cerror clip_indicator(cflag) 

Cclip cflag; /* CLIP_RECTANGLE, VDC_EXTENT. or OFF */ 

The value of the argument cflag determines whether output primitives are clipped before they 
are displayed. The default state is vdc_extent. The advantage of turning clipping off is that it 
improves the speed of drawing primitives. However, if clipping is turned OFF, SunCGI may 
draw output primitives outside of the window or within the bounds of an overlapping window. If 
clipping is not OFF, output primitives are clipped to either the clip rectangle, (if cflag equals 
CLIP) or the full extent of VDC space or (if cflag equals CLIP). 
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'typedef entim { 
CLIP. 

NOCLIP, 

CLIP_RECTANGLE 
} Vclip; 


ERRORS: 

5 ENOTOPOP CGI not in proper state CGI shall be either in state CGOP, VSOP, or 
VSAC. 


2 . 3 . 2 . 2 . clip_rectangle (Ccliprecty 


Cerror clip_rectangle(xmin.xmax,ymin,ymax) 

Cint xmin,xmax,ymin,ymax; /* bottom left-hand 

and top right-hand corner of clipping rectangle */ 

ciip_rectangle defines the clipping rectangle in VDC Coordinates. By default, the clipping 
rectangle is set to the borders of VDC space. The clipping rectangle impacts all view surfaces. 

ERRORS: 


5 

ENOTOPOP 

CGI not in proper state CGI shall be either in state CGOP, VSOP, or 
VSAC. 

20 

EBADRCTD 

Rectangle definition is invalid. 

22 

ECLIPTOL 

Clipping rectangle is too large. 

23 

ECLIPTOS 

Clipping rectangle is too small. 


2.3.3. Device Control 

Device control functions restore the view surface and the internal state of SunCGI to a known 
state. The individual aspects of the device which can be reset are the output attributes, the 
view surface (screen), and the error reporting. 


2.3.3.1. hard_reset (Chardrst^ 

Cerror hard_reset() 

hard_reset returns the output attributes to their default values; terminates all input devices, 
and empties the event queue and clears all view surfaces. VDC Space is reset to its default 
values and the clip indicator is set to CLIP. 
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This function should be used sparingly because most control, attribute, and input functions 
called before this function will not have any effect on functions called after hard_reset is 
called. 

ERRORS: 

5 ENOTOPOP CGI not in proper state CGI shall be either in state CGOP, VSOP, or 
VSAC. 


2.3.3.2. reset_to_defaults (trsttodefs^ 

Cerror reset_to_defaults() 

reset_to_defaults returns output attributes to defaults. reset_to_defaults does not 
clear the screen, reset the input devices, or reset the character set index. 

ERRORS: 

5 ENOTOPOP CGI not in proper state CGI shall be either in state CGOP, VSOP, or 
VSAC. 

10 EVSIDINV Specified view surface name is invalid. 


2.S.3.S. clear_view_surface (Cclrvws^ 


Cerror clear_view_surface (name,defflag^Index) 

Cint name; /* name assigned to cgi view surface */ 

Cflag defflag; /* default color flag */ 

Cint index; /* color of cleared screen */ 

clear_view_surfaco changes all pixels in the relevant area of the view surface specified by 
name to the color specified by the index argument, unless the defflag argument is set to OFF. If 
defflag is equal to OFF, the view surface is cleared to color zero. The area of the view surface 
which is actually cleared is determined by the clear_control function. 
clear_view_surface also resets the internal state of SunCGI according to previous calls to 
the clear_cont;rol function. clear_view_surface resets the current background color 
to the color of the cleared view surface. 


ERRORS: 


4 

ENOTVSAC 

CGI not in proper state: CGI shall be in state VSAC. 

10 

EVSIDINV 

Specified view surface name is invalid. 

13 

EVSNOTOP 

Specified view surface not open. 

15 

EVSNTACT 

Specified view surface is not active. 

35 

ECINDXLZ 

Color index is less than zero. 

36 

EBADCOLX 

Color index is invalid. 
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2 .S.S. 4 . clear_control (Cclrcont^ 


Cerror clear_control(soft,hard,intern,extent) 

Cacttype soft,hard; /* soft-copy action, hard-copy action */ 

Cacttype intern; /* internal action */ 

Cexttype extent; /* clear extent */ 

clear_control determines the action taken when clear_view_surface is called. The 
argument soft can be set to either NO_OP or CLEAR. The argument hard which regulates clearing 
rules for plotters is ignored (because SunCGI does not currently support hard-copy devices) and 
is included only for ANSI CGI compatibility. The argument intern is set to either RETAIN or 
CLEAR. This parameter was included to support segmentation storage which is not currently a 
part of ANSI CGI. Therefore, the intern argument is ignored. The argument clear_extent is 
set to either VIEW_SURFACE, VIEWPORT, or CLIP_RECTANGLE and determines what area of the 
screen is cleared. The default states are CLEAR {»oft), NO_OP [hard), RETAIN (I'nfern), and 
VIEW_SURFACE [extent). 

ERRORS: 

5 ENOTOPOP CGI not in proper state CGI shall be either in state CGOP, VSOP, or 
VSAC. 


2.3.3.5. set_error_warning_mask (tserrwarnmky 


Cerror set:_error_warning_mask (action) 

Cerrtype action; /* Action on receipt of an error */ 

set_error_warning_mask^ determines the action taken by SunCGI when an error occurs. 
Three types of action are possible: NO^ACTION, POLL, INTERRUPT. If the action argument is set 
to NO_ACTION, errors are detected internally, but not reported. 


The user is advised not to set the action argument to NO_ACTION. 

If the action argument is set to POLL, errors are detected and the returned value of the function 
is set to the error number. Error handling is therefore, left up to the application programmer. 
If the action is set to INTERRUPT an error message is printed on the terminal, and the program is 
stopped if the error is FATAL (See Appendix D). The default error_warning_inask is INTER¬ 
RUPT. 

ERRORS: 

5 ENOTOPOP CGI not in proper state CGI shall be either in state CGOP, VSOP, or 
VSAC. 


^ The syntax of set_®rror_warnlng_iiiaBlc in SunCGI is slightly different from the proposed ANa 
standard in that the ANSI definition allows different actions for different classes of errors. 
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2.4. Running SunCGI in the Window System 

Two aspects of SunCGI pertaining to the window system are: 

1. varying the size of graphics windows, and 

2. handling SIGWINCHes (interrupt signals generated by changes to the view surface made by 
the window system). 


2.4.1. Changing the Window Size 

When the window size changes during execution time, the scale factors which map VDC Space 
into screen space are modified. More importantly, unless the application program has explicitly 
opened a view surface as a retained view surface, overlapping other windows destroys the picture 
in the graphics subwindow below, In this case, the picture must be regenerated by re-running the 
application program. 


2 . 4 . 2 . Passing SIGWINCHes to the Application Program 

When a view surface is initialized or changed, the SIGWINCH signal is normally trapped by 
SunCGI. However, the SIGWINCH signal is passed up to the application program if the applica¬ 
tion program provides a SIGWINCH handling routine by using the set_up_sigwirich function. 
Under no circumstances will the user be able to access the SIGWINCHes generated when the view 
surface is initialized. Therefore, the set:_up_sigwinch routine is primarily intended for users 
who want to activate a display list for picture regeneration, for example, when the size of the 
view surface has changed. If the view surface is retained, the pictures is redisplayed if the size 
of the view surface has not changed. 


2.4.3. set_up_sigwinch (Gsupsigj 

Cerror set_up_sigwinch(naine, sig_functlon) 

Clnt name; 

Cint *sig_function0; /* signal handling function */ 

set_up_sigwinch is a nonstandard SunCGI function that allows the application program to 
trap SIGWINCHes for viewsurface name. If the sig_function argument is nonzero, all 
SIGWINCHes which are not trapped by the internals of SunCGI (that is, view surface initializa¬ 
tion, and changing the size of the window) are passed to the function specified by 
sig_function. 

ERRORS: 

5 ENOTOPOP CGI not in proper state CGI shall be either in state CGOP, VSOP, or 
VSAC. 
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Output 


SunCGI supports two classes of output primitives: geometrical output primitives and raster 
primitives. 

Geometrical Output Primitives 

include arcs, circles, polylines, and polygons. The position of geometrical output primitives 
are always specified in absolute VDC coordinates^. 

Raster Primitives 

draw text and scaled and unsealed two-dimensional arrays. The coordinate system for ras¬ 
ter primitives depends on the type of primitive: cell array, pixel array, or bitblt (bit block 
transfer). The drawing mode determines how output primitives are drawn on top of other 
output primitives or the background. 


3.1. Geometrical Output Primitives 

Geometrical output primitives are divided into two classes: polygonal primitives and conical 
primitives. Geometrical output primitives are all two-dimensional in keeping with the CGI stan¬ 
dard. However, polygons with holes (via the part:ial_polygon function) are provided in 
order to support three-dimensional graphics packages. 


3.1.1. Polygonal Primitives 

Most polygonal primitives (polyline, polymarker, polygon, and partial_polygon) 
take one argument of type Ccoorlist: 


^ SunCGI (unlike SunCore) maintains no concept of current position. 
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typedef struct ■{ 

Cint x; 

Clnt y; 

} Ccoor; 

typedef struct { 

Ccoor *ptlist; 

Cint n; 

} Ccoorlist; 

The element pHitt is really a pointer to an array of type Ccoor which contains the coordinates 
of the points defining the primitive. The style, color, and other features of lines, markers, and 
fill patterns used by geometrical output primitives are set by the attribute functions described in 
the next chapter. 

The polygons generated by SunCGI may or may not be closed. SunCGI automatically assumes 
the polygon is closed for the purpose of filling. However, a polygon must be explicitly closed in 
order to get all of its edges drawn, so take care to generate explicitly closed polygons. However, 
the rectangle function implicitly generates closed objects®. 


S.1.1.1. polyline ^Cpolyline^ 


Cerror polyline(polycoors) 

Ccoorlist *polycoors; /* list of points */ 

polyline draws lines between the points specified by the ptlist element of polycoors. polyline does 
not draw a line between the first and last element of the point list. To generate a closed poly¬ 
line, the last point on the list must have the same coordinates as the first point on the list. The 
style, color, and width of the lines are set by the polyline_bundlo_index, line_type, 
line_color, line_width, and line_wid-th_specification_niode functions. If a line 
segment of a polyline has a length of zero, the line is not drawn. To draw a point use the ctrcle 
function. If you specify a polyline that has less than two points an error is generated. Similarly, 
if the number of points specified is greater than the maximum number of points (255), an error is 
generated. 

ERRORS: 

4 ENOTVSAC CGI not in proper state: CGI shall be in state VSAC. 

60 ENMPTSTL Number of points is too large. 

61 EPLMTWPT polylines must have at least two points. 

S.1.1.2. disjoint_polyline CCdpolyline^ 


® The only instance in which rectangle does not produce a closed object is if one of the corners exceeds a 
clipping boundary. 
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Cerror disjoint_polylino(polycoors) 

Ccoorlist ‘polycoors; /* list: of points •/ 

disjoint_polyline draws lines between pairs of elements in ptUst. The style, color, and 
width of the lines are set by the polyline_bundlo_index, line_type, line_color, 
line_width, and line_width_specification_mode functions. If polycoors contains an 
odd number of points, the last point is ignored. As with polyline, if the number of points is 
less than two or greater than 258, an error is generated, disjoint_polyline is typically 
used to implement scan-line polygon filling algorithms. 

ERRORS: 

4 ENOTVSAC CGI not in proper state: CGI shall be in state VSAC. 

60 ENMPTSTL Number of points is too large. 

61 EPLMTWPT polylines must have at least two points. 


S.1.1.3. polymarker ^Cpolymarker^ 



Cerror polymarker(polycoors) 

Ccoorlist ‘polycoors; /* list of points */ 

polymarker draws a marker at each point. The type, color, and size of marker are set by the 
polymarker_bundle_index, marker_'typo, marker_color, marker_size, and 
marker_size_specification_mode functions. If the number of points specified is greater 
than the maximum number of points, an error is generated, polymarker is useful for making 
graphs such as scatter plots. 

ERRORS: 

4 ENOTVSAC CGI not in proper state: CGI shall be in state VSAC. 

60 ENMPTSTL Number of points is too large. 



3. 1 . 1 . 4 . polygon ^Cpolygon^ 

Cerror polygon(polycoors) 

Ccoorlist ‘polycoors; /‘ list of points */ 

polygon displays the polygon described by the points in polycoors. In addition, any points added 
to the global polygon list by the partial_polygon function are also displayed. The polygon is 
filled between edges. Polygons are allowed to be self-intersecting. The visibility of individual 
edges can only be set by the part:ial_polygon function. The pattern and color used to fill 
the polygon are set by the functions described in the solid attributes section of the attributes 
chapter. The characteristics of the edges are controlled by the perimeter attribute functions and 
not the line attribute functions (which regulate the drawing of polylines). The number of points 
in the polygon used to determine the error condition of too few points is the total number of 
points on the global polygon list not the number of points specified in polycoors. 

ERRORS: 
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4 ENOTVSAC 
60 ENMPTSTL 

62 EPLMTHPT 

63 EGPLISFL 


CGI not in proper state: CGI shall be in state VSAC. 
Number of points is too large. 

Polygons must have at least three points. 

Global polygon list is full. 


3.1.1.5. partial_polygon ^Cppolygon^ 

Cerror partial_polygon(polycoors, flag) 

Ccoorllst *polycoors; /* list of points */ 

Ccflag flag; /* add to point buffer */ 

partial_polygon adds elements to the global polygon list without displaying the polygon. 
The flag controls whether the previous polygon on the global polygon list is open or closed. If the 
cflag is set to CLOSED, the last polygon on the global polygon list is closed by drawing a visible 
perimeter edge between the last and the first points of the last polygon in the global polygon list. 
If the cflag is set to OPEN, an invisible perimeter edge is drawn between the last and the first 
points of the last polygon in the global polygon list. The partial_polypri function provides 
the capability of drawing multiple-boundary polygons, including polygons with holes. 
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#include "cgidefs.h" 


Ccoor list[4]; 
Ccoorlist points; 



interior_stylo(SOLIDI,ON); 

list[0] .X = 10000; 

list[0].y = 10000; 

list[1] .X = 10000; 

list [1] .y 20000; 

list[2] .X = 20000; 

list[2].y = 20000; 

list[3] .X = 20000; 

list[3].y = 10000; 

points.ptlist=list; 

points.n=4; 

partial^olygon(fipoints,CLOSE); /* draw large solid square */ 

list [0]ix = 12500; 

list[O].y = 12500; 

llst[l].x = 12500; 

list[1].y = 17500; 

list[2] .X = 17500; 

list[2].y = 17500; 

list[3] .X = 17500; 

list[3].y = 12500; 

points.ptlist=list; 

points.n=4; 

polygon(fipoints); /* cut a hole in it */ 

} 


An error is detected if the number of points on the global polygon list exceeds 255. In this case, 
the polygon on the global polygon list is drawn, and the new information is not added. The same 
error handling applies to polygon. 

ERRORS: 


4 ENOTVSAC 
60 ENMPTSTL 

62 EPLMTHPT 

63 EGPLISFL 


CGI not in proper state: CGI shall be in state VSAC. 
Number of points is too large. 

Polygons must have at least three points. 

Global polygon list is full. 


3,1.1.6. rectangle /Greetanglo^ 
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Cerror rectangle(rbc, Itc) 

Ccoor *rbc,*ltc; /* corners defining rectangle */ 

rectangle displays a box with its lower right-hand corner at point rbc and its upper left-hand 
corner at point Itc. The fill pattern is determined by the solid object attribute functions. Calls 
to rectangle do not affect the global polygon list. The interior of the rectangle (the filled portion) 
is defined by Ire and ulc. The perimeter is drawn outside of this region. The appearance of the 
rectangle is determined by the fill area and perimeter attributes. 

If the arguments to rectangle would result in a point or a line, the point or line is drawn. How¬ 
ever, if the arguments to rectangle determine a point, the point is drawn with width zero, 
regardless of the current value of perimeter^width. If the values of Ire and ulc are reversed, the 
points are automatically reversed and the rectangle is drawn normally. 

ERRORS: 

4 ENOTVSAC CGI not in proper state: CGI shall be in state VSAC. 

3.1.2. Conical Primitives 

SunCGI has two classes of conical primitives: circular and elliptical. Each class has functions 
for drawing solid objects, arcs, and closed arcs. Drawing of conical primitives is regulated by the 
same attributes that regulate the drawing of polygons and polylines. 


3.1.8.1. circle CCcircle^ 


Cerror circle(cl, rad) 

Ccoor *cl; /* center */ 

Cint rad; /* radius */ 

circle draws a circle of radius rad centered at cl. The argument rad is expressed in terms of 
VDC Space. The color, form, and visibility of the interior and perimeter are controlled by the 
same solid object attributes which control the drawing of polygons and rectangles. 

The argument rad determines the size of the inside of the circle. Therefore, a circle with a thick 
perimeter may be larger than expected. If the radius is zero, a point is drawn, and no textured 
perimeter is drawn, even if the perimeter width is large. If the radius is negative, the absolute 
value of the radius is used. 

Textured circles may possibly contain an incorrect element at one point because the digital cir¬ 
cumference may not be exactly divisible by the length of the texture element. 

ERRORS: 

4 ENOTVSAC CGI not in proper state: CGI shall be in state VSAC. 

S.1.8.8. circular_arc_cen'ter (Ccircarccent^ 
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Cerror circular_arc_center(cl, c2x, c2y, c3x, c3y, rad) 

Ccoor *cl; /* center */ 

Cint c2x,c2y,c3x,c3y; /* endpoints */ 

Cint rad; /* radius */ 

circular_arc_center draws a circular arc through points c2z, c2y and cSx, eSy with circle 
of radius rad at center cl. Point e2x, e2y is the starting point and point cSx, cSy is the ending 
point. If c2x, c2y or cSx, cSy are not on the circumference of the circle, an error is generated 
and the arc is not drawn. Circular arcs are drawn in a counterclockwite manner. This conven¬ 
tion is used to determine the difference between the arc formed by the obtuse angle determined 
by cl.x, cl.y, c2x, c2y, and cSx, cSy and the acute angle specified by these same points. There¬ 
fore switching the values of c2x, c2y and cSx, cSy will produce complementary arcs. 

If rad is negative, the points 180 degrees opposite from c2x, c5y-and cSx, cSy are used as the 
endpoints of the arc. 

If the rad is zero, a point is drawn at cl. If either c2x, c2y or cSx, cSy are not on the perimeter 
of the circle determined by cl and rad, an error is generated and the arc is not drawn. The 
attributes which determine the style, width, and color of the arc are the same functions which 
regulate the drawing of poly/me«. 

ERRORS: 

4 ENOTVSAC CGI not in proper state: CGI shall be in state VSAC. 

64 EARCPNCI Arc points do not lie on circle. 

S.1.2.3. circular_arc_cent:er_close (tcircarccentcl^ 


Cerror clrcular_arc_center_closa(cl, c2x, c2y, c3x, c3y, rad, close) 
Ccoor *cl; /* center */ 

Cint c2x,c2y,c3x,c3y; /* endpoints */ 

Cint rad; /* radius */ 

Cclosetype close; /* PIE or CHORD */ 

circular_arc_center_close draws a closed arc centered at el with radius rad and end¬ 
points c2x, c2y and cSx, cSy. Arcs are closed with either the PIE or CHORD algorithm. The PIE 
algorithm draws a line from each of the endpoints of the arc to the center point of the circle. 
SunCGI then fills this region as it would any other solid object (that is, it uses the fill area attri¬ 
butes). The CHORD algorithm draws a line between the endpoints of the arc and then fills this 
region. circular_arc_center_close is useful for drawing pie charts (see following exam¬ 
ple): 
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#lnclude <cgidefs.h> 


■{ /* draws four quadrants in different colors */ 
Cint radius; 

Ccoor cl; 



inter ior_style(SOLIDI.OFF) /* set arc typo to SOLID and no visible perimeter */ 
cl.x = 16000; /* center */ 
cl.y = 16000; 

radius =8000; /* radius */ 

fill_color(1); /* color of quadrant 1 */ 

circular_arc_center_closo(&cl,16000,24000,24000,16000,radius,PIE); 
fill_color(2); /* color of quadrant 2 */ 

circular_arc_center_clos 0 (&cl,16000,24000,12000,16000,radius,PIE); 
fill_color(3); /* color of quadrant 3 */ 

circular_arc_center_closo(&cl,12000,16000,12000,16000,radius,PIE); 

fill_color(4); /* color of-quadrant 4 */ 

circular_arc_center_olose(&cl,12000,16000,24000,16000,radius,PIE); 
sleep (10) ; 

} 


ERRORS: 

4 ENOTVSAC CGI not in proper state; CGI shall be in state VSAC. 

64 EARCPNCI Arc points do not lie on circle. 

3. 1 . 2 . 4 . circular_arc_3pt ("Ccircarcthree^ 

Cerror circular_arc_3pt(cl, c2, c3) 

Ccoor *cl,*c2,*c3; /* starting, intermediate, and ending points */ 
Cint rad; /* radius */ 

circular_arc_3pt draws a circular arc starting at point el and ending at point c3 which is 
guaranteed to pass through point c2. If the circular arc is textured (for example, dotted) then 
the intermediate point may not be displayed. However, if the arc is solid, the intermediate point 
is always drawn. If the three points are colinear, a line is drawn. If two of the three points are 
coincident, a line is drawn between the two distinct points. Finally, if all three points are coin¬ 
cident, a point is drawn. circular_arc_3pt; is considerably slower than 
circular_arc_center, therefore, you are advised to circular_arc_center if both func¬ 
tions can meet your needs. 

ERRORS; 

4 ENOTVSAC CGI not in proper state: CGI shall be in state VSAC. 
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5.1.2.5. circular_arc_3pt_close ^Ccircarcthreeciy 

Cerror circular_arc_3pt_closo(cl, c2, c3, close) 

Ccoor *cl, *c2, *c3; /* starting. Intermediate, and ending points */ 
Cclosetype close; /* PIE or CHORD */ 

circular_arc_3pt_close draws a circular arc starting at point cl and ending at point cS 
which is guaranteed to pass through point e2. As with circular_arc_3pt, 
circular_arc_3pt_close is considerably slower than circular_arc_center_close; 
therefore, you are advised to use circular_arc_center_close if both functions meet your 
needs. 

If the three points are colinear, a line is drawn. If two of the three points are coincident, a line 
is drawn between the two distinct points. Finally, if all three points are coincident, a point is 
drawn. In none of these cases will any region be filled. 

ERRORS: 

4 ENOTVSAC CGI not in proper state: CGI shall be in state VSAC. 

5.1.2.6. ellipse ^Cellipsey 

Cerror ellipse (cl, majx,mlny) 

Ccoor *cl; /* center */ 

Cint majx,miny; /* enpoints of x and x axes */ 

ellipse draws an ellipse centered at point cl with major(x) and minor (y) axes which terminate at 
majx and miny^^. If either majx or miny are zero, a line is drawn. If both majx and miny are 
zero, a point is drawn. The attributes which control the drawing of ellipses are the same as 
those attributes which control the drawing of circles and rectangles (namely, the perimeter and 
fill area attributes). 

ERRORS: 

4 ENOTVSAC CGI not in proper state: CGI shall be in state VSAC. 

5.1.2.7. elliptical_arc (Celliparc^ 

Cerror elliptical_arc(cl, sx, sy, ex, ey, majx, miny) 

Ccoor *cl;/* center */ 

Cint sx,sy; /* starting point of arc */ 

Cint ex,ey; /* ending point of arc */ 

Cint majx,miny; /* endpoints of major and minor axes */ 

'.■> 

elliptical_arc draws an elliptical arc centered at cl with major(x) and minor (y) axes which 
terminate at majx and miny. Sx, sy and ex, ey are the starting and ending points of the arc. An 
error is generated (and the ellipse is not drawn) if the points {sx, sy, and ex, ey) are not on the 

Although the axes are called the major and minor axes by the standard they are really the x and y 
axes. In fact, the x-axis can either be the major or minor axis, depending on the relative length of the y-axis. 
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perimeter of the ellipse. Circular arcs are drawn in a counterclockwise manner. This convention 
is used to determine the difference between the arc formed by the obtuse angle determined by 
cl.x, cl.y, sx, sy, and ex, ey and the acute angle specified by these same points. Therefore 
switching the values of sx, sy and ex, ey will produce complementary arcs. 

If either majx or miny are zero, a line is drawn. If both majx and miny are zero, a point is 
drawn. 

ERRORS: 

4 ENOTVSAC CGI not in proper state: CGI shall be in state VSAC. 

65 EARCPNEL Arc points do not lie on ellipse. 

S.1.2.8. ellipt:ical_arc_close ^Celliparcclj 

Cerror elliptical_arc_close(cl, sx, sy, ex, ey, majx, miny, close) 

Ccoor *cl;/* center */ 

Cint sx,sy; /* starting point of arc */ 

Cint ex,ey; /* ending point of arc */ 

Cint majx,miny; /• enpoints of major and minor axes */ 

Cclosetype close; /* PIE or CHORD */ 

elliptical_arc_closo draws an elliptical arc specified by sx, sy, ex, ey, and majx, miny 
The arc is closed with either the PIE or CHORD algorithm. The same restrictions on sx, sy, ex, 
and ey are applied to elliptical_arc_closo as to elliptical_arc. However, 
elliptical_arc_close uses the fill area and perimeter attributes, whereas 
elliptical_arc_close uses the line attributes. 

If either majx or miny are zero, a line is drawn. If both majx and miny are zero, a point is 
drawn. In neither of these cases will any region be filled. 

ERRORS: 

4 ENOTVSAC CGI not in proper state: CGI shall be in state VSAC. 

65 EARCPNEL Arc points do not lie on ellipse. 

3.2. Raster Primitives 

Raster primitives include text, cell arrays, pixel arrays, and bitblts (bit block transfer). BitbIts 
are pixel arrays (bitmaps) which can be drawn using the various drawing modes. The current 
drawing mode determines how bitbIt primitives are affected by information which is already on 
the screen. Raster primitives differ from geometrical primitives because their dimensions are not 
necessarily expressed in VDC Space. Therefore, you must be careful to consider whether position 
arguments are expressed in VDC Space or screen coordinates. 


3 . 2 . 1 . text ('Ctextj 
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Cerror text(cl, tstrlng) 

Ccoor cl; /* starting point of text (in VDC Space) */ 

Cchar *tstring; /* text */ 

text displays the text contained in tstring at point cl (expressed in VDC Space). The appearance 
of text is controlled by the text attributes described in the next chapter; however, it is worth 
noting some of the effects of the most important attribute, text precition. The size of the text 
depends on the setting of the text precmon (see the •text_precision function) and the font 
selected. The results of clipping also depend on the text precmon attribute (unless the text pre¬ 
cision is set to STROKE). Control characters are displayed as blanks, except in the SYMBOL font 
where they may be drawn as pictures of bugs. 

ERRORS: 

4 ENOTVSAC CGI not in proper state: CGI shall be in state VSAC. 

5.2.2. vdin_text (Cvdmtext^ 

Cerror vdin_text (cl, flag, tstring) 

Ccoor cl; /* starting point of text (in VDC Space) */ 

Ctextfinal flag; /* final text for alignment */ 

Cchar *tstring; /* text */ 

vdin_text displays the text contained in tstring at point cl (expressed in VDC Space). The 
intended difference between text and vdm_text is that vdm^text allows control characters; 
however, SunCGI does not handle control characters so text drawn with vdm_text will appear 
identical to text drawn with the text function. If the flag argument is equal to FINAL, the previ¬ 
ous text and the appended text are aligned separately. However, if the flag argument is equal to 
NOTJ’INAL, the appended and previous text are aligned together. 

ERRORS: 

4 ENOTVSAC CGI not in proper state: CGI shall be in state VSAC. 

3.2.3. append_text (Captext^ 


Cerror append_text(flag, tstring) 

Ctextfinal flag; /* final text for alignment */ 

Cchar ‘tstring; /* text */ 

append_text displays the text contained in tstring after the end of the most recently written 
text. The type of text written depends on the same attributes which control the display of text. 
The flag argument determines whether the appended text is aligned with the previous text if the 
alignment is CONTINUOUS. If the flag argument is equal to FINAL, then the previous text and the 
appended text are aligned separately. However, if the flag argument is equal to NOTJFINAL, the 
appended and previous text are aligned together. 

ERRORS: 

4 ENOTVSAC CGI not in proper state: CGI shall be in state VSAC. 
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3 . 2 . 4 . inquire_text_extent /Oqtextext^ 


Cerror inquiro_text_©xtent(tstrlng, nextchar, concat, lleft, uleft, uright) 
Cchar *tstring; /* text */ 

Cchar nextchar; /* last character */ 

Ccoor *concat; /* concatenation point */ 

Ccoor *lleft,‘uleft,‘uright; /‘ coordinates of 

text bounding box ‘/ 

inquire_text_extent determines how large text Mring would be and where it would be 
placed if it were drawn using the current text attributes. The nextchar parameter is used to 
determine the point where text would start if more text (starting with nextchar) were appended 
to the text specified by tatring^^. If nextchar equals the last point of the current character is 
used. The argument concat returns the coordinates of the point where appended text would 
start. The arguments lleft, uleft, and uright return the coordinates of the bounding box of text 
contained in tatrtng. 

The values of lleft, uleft, and uright are defined by the bounding box of the character and there¬ 
fore may not be at the exact pixel where the character ends or begins. 

ERRORS: 

4 ENOTVSAC CGI not in proper state: CGI shall be in state VSAC. 

3.2.5. cell_array (Ccellarr^ 

Cerror cell_array(p, q, r, dx, dy, colorind) 

Ccoor ‘p, ‘q, ‘r; 

/* corners of parallelogram (in VDC Space) */ 

Cint dx,dy; /‘ dimensions of color array */ 

Cint ‘colorind; /‘ array of color values ‘/ 

cell_array draws a scaled and skewed pixel array on the view surface(s). Points p, g,and r 
(expressed in VDC Space) define a parallelogram. Line p-q is a diagonal and p is the lower left- 
hand corner, r is one of the remaining two corners, dx and dy define the width and the height 
of the array colorind which is mapped onto the parallelogram defined by p,q, and r. 

cell_array is one of the few primitives which depends on the actual size of the view surface. 
Cell arrays are not drawn if the elements of the array would be smaller than one pixel. How¬ 
ever, because different view surfaces may have different dimensions, a cell array might be drawn 
on one view surface, but not on another smaller view surface. Finally, all cells composing the 
cell array are the same size; therefore, the upper left hand corner of the cell array might be 
down and to the right of point q because of the accumulated error of making all of the cells 
slightly smaller than their floating point size. For example if each cell of a three-by-three cell 
array is supposed to be 3.333 pixels wide, the actual cell array will be nine pixels wide instead of 
ten. 

ERRORS: 


This is a method for accounting for proportional spacing. 
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4 ENOTVSAC 

66 ECELLATS 

67 ECELLPOS 


CGI not in proper state; CGI shall be in state VSAC. 
Cell array dimensions dx,dy are too small. 

Cell array dimensions must be positive. 




S.2.6. pixel_array (Cpixarr^ 


Cerror plxol_array (pcell,m,n,colorind) 

Ccoor *pcell; /* base of array in VDC Space */ 

Cint m,n; /* dimensions of color array in screen space */ 

Cint *colorind; /* array of color values */ 

pixel_array draws array colorind starting at point pceW (expressed in VDC Space), m and n 
(expressed in screen space) define the x- and y-dimensions of the array. Therefore, pixel arrays 
always have a constant physical size, independent of the dimensions of VDC Space. The pixel 
array is drawn down and to the right from point pcell. If either m or n are not positive, the 
absolute value of m and n are used. pixel_array is not affected by the current drawing 
mode. 

ERRORS: 

4 ENOTVSAC CGI not in proper state: CGI shall be in state VSAC. 

69 EVALOVWS Value outside of view surface. 

S.2.7. bitblt_source_array (Cbtblsouarr^ 

Cerror bitblt_sourco_array(pixsource, xo, yo, xe, ye, pixtarget, xt, yt, name) 
Cpixrect *pixsource,‘pixtarget; /* source and target pixel arrays */ 

Cint xo,yo; /* coordinates of source pixel array (in VDC Space) */ 

Cint xe,ye; /‘ dimensions of source pixel array (in screen space) */ 

Cint xt.yt; /* coordinates of target pixel array (in VDC Space) */ 

Cint name; /* view surface name */ 

bitblt_source_array moves a pixel array from point {zo,yo) to point {xt,yt) using the 
current drawing mode. Both of these points are expressed in VDC Space. The size of the pixel 
array is determined by the xe and ye arguments which are expressed in screen space. Pixsource 
and pixtarget are pixrects^^ which contain the bitmaps at the source and target destinations. An 
error is detected if either xe or ye are not positive. If the replicated pattern array overlaps with 
the source array on the screen, the visual result depends on the current drawing mode, pix- 
source and pixtarget may have different contents depending on the screen drawing mode (see the 
set_drawing_mode function). 

Multiple view surfaces and bitblt’s are incompatible, so a name argument must be specified. 

ERRORS; 

4 ENOTVSAC CGI not in proper state; CGI shall be in state VSAC. 


Refer to the Programmers’ Reference Manned for Sun Winious for more information about pixrects. 
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69 EVALOVWS Value outside of view surface. 


3.S.8. bitblt_pattern_array ^Cbtblpatrarr^ 


Cerror bitblt_pattern_array(pixpat, px, py, pixtarget. rx, ry, 
ox, oy, dx, dy, name) 

Cpixrect *pixpat; /* pattern source array */ 

Clnt px,py; /* pattern extent */ 

Cpixrect ‘plxtarget; /* destination pattern array */ 

Cint rx,ry; /* pattern reference point */ 

Cint ox,oy; /* destination origin */ 

Cint dx,dy; /* destination extent */ 

Cint name; /* view surface name */ 

bitblt_pattern_array replicates the pattern (using the current drawing mode) stored in 
pizpat to fill the area of array pixtarget which is determined by ox, og, and dx, dy. The pattern 
reference point determines the offset of pattern array from the point zero. The resultant pattern 
array is displayed at ox, oy. If the replicated pattern array overlaps with the source array on 
the screen, the visual result depends on the current drawing mode. 

Pixpat is a pointer to a pixrect which must be created by the application program. If pixpat is 
not a pointer to an existing pixrect, an error is generated. Pixtarget is a pointer to a pixrect 
which is created by a bitblt_patt:ern_array. 

Multiple view surfaces and bitblt’s are incompatible, so a name argument must be specified. 


ERRORS: 


4 

ENOTVSAC 

CGI not in proper state: CGI shall be in state VSAC. 

69 

EVALOVWS 

Value outside of view surface. 

70 

EPXNOTCR 

Pixrect not created. 

S.3.9. 

bitb 1 t_patterned_source_array (Chth Ipatsouarr ) 


Cerror bitblt_patterned_source_array(pixpat, px, py, pixtarget, rx, ry, 
plxsource, sx, sy, ox, oy, dx, dy, name) 

Cpixrect ‘pixpat; /* pattern source array */ 

Cint px,py; /* pattern extent */ 

Cpixrect ‘plxsource; /‘ source array ‘/ 

Cint sx,sy; /‘ source origin ‘/ 

Cpixrect ‘pixtarget; /‘ destination pattern array */ 

Cint rx,ry; /‘ pattern reference point ‘/ 

Cint ox,oy; /* destination origin ‘/ 

Cint dx,dy; /‘ destination extent */ 

Cint name; /‘ view surface name ‘/ 

bitblt;_patterned_source_array replicates the pattern (using the current drau'tnj; mode) 
stored in pixpat to fill the area of array pixtarget which is determined by ox, oy, and dx, dy. The 
replicated pattern array is ANDed into the pixrect pointed to by pixeource before the array is 
copied to pixtarget. The pattern reference point determines the offset of pattern array from the 
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point zero. The resultant pattern array is displayed at ox, oy. If the replicated pattern array 
overlaps with the source array on the screen, the visual result depends on the current drawing 
mode. Pixpat is a pointer to a pixrect which must be created by your application program. 
Pixgouree and pixtarget are pointers to pixrects which are created by a 
bitb1t_patterned_source_array. 

Multiple view surfaces and bitblt’s are incompatible, so a name argument must be specified. 
ERRORS: 

4 ENOTVSAC CGI not in proper state: CGI shall be in state VSAC. 

69 EVALOVWS Value outside of view surface, 

70 EPXNOTCR Pixrect not created. 


3.2.10. inquire_cell_array /Cqcellarr^ 



Cerror inquire_cell_array(name, p, q, t, dx, dy, colorlnd) 

Cint name; /* view surface name */ 

Ccoor *p, *q, *r; /* corners of parallelogram 

(in VDC Space) */ 

Cint dx,dy; /* dimensions of color array */ 

Cint *colorind; /* array of color values */ 

Points p, and r (in VDC Space) define a parallelogram with line p-q as the diagonal where p is 
the lower left-hand corner, r is one of the remaining two corners, dx and dy define the width 
and the height of the array colorind which contains the colors of the pixels on the screen which 
lie within the parallelogram defined by p,q, and r. Notice that a view surface identifier, name, 
must be specified because the result of this function is highly dependent on the dimensions and 
contents of the view surface. 

The area of the screen corresponding to the parallelogram is assumed to contain a regular grid of 
points. However, if each element of the grid is larger than one pixel, the color of the pixel at 
lower left-hand corner of each element of the grid is defined to be the color of the grid element. 
Therefore, the values contained in colorind are highly dependent on the size of the view surface. 
An error is produced if the elements of the grid are smaller than one pixel. 


ERRORS: 


4 

ENOTVSAC 

CGI not in proper state: CGI shall be in state VSAC. 

10 

EVSIDINV 

Specified view surface name is invalid. 

13 

EVSNOTOP 

Specified view surface not open. 

15 

EVSNTACT 

Specified view surface is not active. 

66 

ECELLATS 

Ceil array dimensions dx,dy are too small. 

67 

ECELLPOS 

Cell array dimensions must be positive. 
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3.2.11. inquire_pixel_array ^Cqpixarr,^ 

Corror inquiro_pixol_array(p, m, n, colorlnd, name) 

Ccoor *p; /* base of array in VDC Space */ 

Clnt m.n; /* dimensions of color array in screen space */ 

Cint *colorind; /* array of color values */ 

Cint name; /* view surface name */ 

inquire_pixel_array fills array colorind with the values of pixels in the area of the screen 
defined by point p (expressed in VDC Space) and m and n (expressed in screen space). The array 
is filled down and to the right from point p. If either m or n are not positive, the absolute value 
of these arguments is used. 

Multiple view surfaces and bitblt’s are incompatible, so a name argument must be specified. 
ERRORS: 

4 ENOTVSAC CGI not in proper state: CGI shall be in state VSAC. 

69 EVALOVWS Value outside of view surface. 

70 EPXNOTCR Pixrect not created. 

3.2.12. inquire_device_bitniap (Cqdevbtmp^ 

Cplxrect *inquire_device__bitmap (name) 

Cint name; /* name assigned to cgi view surface */ 

inquire_device_bitmap returns the pixrect which corresponds to the view surface. If you 
want to use subareas of this pixrect or manipulate it any other way, refer to the Pixrects 
Chapter in the Programmers’ Reference Manual for Sun Windows. Pixrects may be created in 
other manners; again refer to the Pixrect Chapter in the Programmers’ Reference Manual for 
Sun Windows. 

ERRORS: 

5 ENOTOPOP CGI not in proper state CGI shall be in in state VDOP, VSOP, or 

VSAC. 


3.2.13. inquire_bitblt_alignnients (Cqbtblalign^ 

Cerror inquire_bitblt_alignments(base, width, px, py, maxpx, maxpy, name) 
Cint ‘base; /* bitmap base alignment */ 

Cint ‘width; /* width alignment */ 

Cint ‘px,*py; /* pattern extent alignment */ 

Cint ‘maxpx,*maxpy; /‘ maximum pattern size ‘/ 

Cint name; /‘ name assigned to cgi view surface ‘/ 

inciuire_bitblt_alignments reports the alignment criteria which are necessary for some 
implementations. These factors are not critical for SunCGI. However, you should keep in mind 
the appropriate depth for the pbcrect when talking to a specific device. Therefore the arguments 
base, width, px, and py are always set to zero. The arguments maxpx and maxpy are device 
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dependent and determine the maximum size of a pattern for bitblt_pat:tern_array and 
bitb1t_patterned_source_array. 

Multiple view surfaces and bitblt’s are incompatible, so a name argument must be specified. 


ERRORS: 


4 

ENOTVSAC 

CGI not in proper state: CGI shall be in state VSAC. 

10 

EVSIDINV 

Specified view surface name is invalid. 

13 

EVSNOTOP 

Specified view surface not open. 

15 

EVSNTACT 

Specified view surface is not active. 


3.3. Drawing Modes 

Drawing modes determine the result of drawing any output primitive on the clear screen (back¬ 
ground) or on top of a previously drawn object. Drawing modes only affect the drawing of bitblt 
primitives. However, a non-standard set:_global_drawing_mode function is provided, 
which affects all output primitives except bitblt’s. Resetting the drawing mode in the middle of 
an application program only affects those output primitives drawn after the mode is reset. The 
novice user is advised not to reset the drawing mode until the user has written at least one appli¬ 
cation program using SunCGI. 


S.3.1. set_drawing„niode (tsdrawmode^ 

Cerror set_drawing_iiiode(visibility, source, destination, combination) 
Cbmode visibility; /* transparent or opaque */ 

Cbitmaptype source; /* NOT source bits */ 

Cbitmaptype destination; /* NOT destination bits */ 

Ccombtype combination; /* combination rules */ 

set_drawing_mode determines the current drawing mode which in turn determines how bitblt 
primitives are displayed. The visibility argument determines how pixels with index zero are 
treated. 

typedef enxim ■( 

TRANSPARENT, OPAQUE 

} Cbmode; 

typedef enum { 

BITTRUE, BITNOT 

)• Cbitraaptypo; 

typedef enum ■( 

REPLACE, AND, OR, NOT, XOR 

)• Ccombtype; 

If visibility is set to TRANSPARENT, all source pixels with index zero leave the destination pixel 
unchanged, regardless of the operation, whereas if visibility is set to OPAQUE, all pixels are 
treated normally. The arguments source and destination determine whether the contents of the 
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source and destination pixrects are NOTted before the bitblt operation is performed. 

The combination argument determines how the source and destination pixrects are combined. 
If combination is equal to REPLACE, the source pixrect (after optionally being NOTted) replaces 
the destination pixrect. If combination is equal to AND, OR, NOT, or XOR the source pixrect and 
the destination pixrect are combined in the indicated Boolean fashion. 

ERRORS: 

5 ENOTOPOP CGI not in proper state CGI shall be in in state VDOP, VSOP, or 
VSAC. 


S.3.2. set_global_drawing_mode (Csgldravnnodej 

Cerror set_global_drawing_mode (combina'tlon) 

Ccombtype combination; /* combination rules */ 

set_global_drawing_mode determines the current global drawing mode which in turn deter¬ 
mines how all output primitives except titbit’s are displayed. The combination argument deter¬ 
mines how the source and destination pixrects are combined. If combination is equal to REPLACE 
(the default value) the output primitive replaces the destination background. If combination is 
equal to AND, OR, or XOR the output primitive and the information on the screen are combined in 
the indicated Boolean fashion. 

ERRORS: 

5 ENOTOPOP CGI not in proper state CGI shall be in in state VDOP, VSOP, or 
VSAC. 


S.S.S. inquire_drawing_Tnode (Cqdrawmode^ 


Cerror inquire_drawing_mode(visibility, source, destination, combination) 
Cbmode ‘visibility; /* transparent or opaque */ 

Cbitmaptype ‘source; /‘ NOT source bits ‘/ 

Cbitmaptype ‘destination; /‘ NOT destination bits ‘/ 

Ccombtype ‘combination; /‘ combination rules ‘/ 

The inc[uire_drawing_mode returns the values of the four components of the current draw¬ 
ing mode. 

ERRORS: 

5 ENOTOPOP CGI not in proper state CGI shall be in in state VDOP, VSOP, or 
VSAC. 
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The current attributes determine how output primitives are displayed. Attributes are not 
specific to any view surface, but affect all view surfaces. If you want to avoid using the attribute 
functions, the current attributes are set to their default attributes which are defined in Table 4- 
1. The current attributes may be set either individually or in groups (by changing the index into 
the bundle table). Each entry in the bundle table specifies a set of attributes for a particular 
type of primitive (for example, solid objects). The method for setting the current attributes 
depends on the state of the ASF {aspect source flag) for each attribute. For individual attribute 
functions to have an effect, the ASF must be set to INDIVIDUAL. If the ASF is set to BUNDLED, the 
current attribute is defined by the entry in the bundle table pointed to by the bundle index. 

The majority of this chapter is devoted to individual attribute functions. Individual attribute 
functions are grouped according to the output primitives they effect: polylines, polymarkers, 
filled objects, and text. The color..table function (which redefines color table entries) is also 
included in this chapter. Finally, functions for obtaining the values of the current attributes are 
discussed. 
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Table 4-1: Default Attributes 


Attribute 

Value 

Attribute 

Value 

All ASFs 

INDIVIDUAL 

All Bundle Indices 

1 

Line Type 

SOLID 

Line Endstyle 

POINT 

Line Width Specification Mode 

SCALED 

Line Width 

0.0 

Line Color 

1 



Marker Size Specification Mode 

SCALED 

Marker Size 

0.0 

Marker Color 

1 



Fill Style 

HOLLOW 

Fill Visible 

ON 

Fill Color 

1 

Fill Hatch Index 

0 

Fill Pattern Index 

1 

Number of Pattern Table Entries 

2 

Pattern Reference Point 

0,0 

Pattern Size 

300,300 

Perimeter Style 

SOLID 

Perimeter Width Specification Mode 

SCALED 

Perimeter Width 

0.0 

Perimeter Color 

1 

Fontset 

1 

Current Font 

STICK 

Text Precision 

STRING 

Character Expansion Factor 

1.0 

Character Space 

0.1 

Character Color 

1 

Character Height 

1000 

Character Base.* 

0.0 

Character Base.y 

0.0 

Character Up.* 

1.0 

Character Up.y 

1.0 

Character Path 

RIGHT 

Horizontal Text Alignment 

NRMAL 

Vertical Text Alignment 

NORMAL 

Text Continuous Alignment.* 

1.0 

Text Continuous Alignment.!/ 

1.0 


4.1. Bundled Attribute Functions 

The attribute environment selector functions determine if the current attributes are defined indi¬ 
vidually or by using a set of attributes (bundles). Bundles are defined by entries in the bundle 
table. The CGI standard specifies the bundle table as read-only but SunCGI allows user- 
definition of entries in the bundle table. 


4.1.1. set_aspect_source_flags (Csaspsouflags^ 


Cerror set_aspect_source_flags(flags) 

Cflaglist ‘flags; /* list of ASFs */ 
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set_aspect_source_flags determines whether individual attributes are set individually or 
from bundle table entries. 

typedef struct •{ 

Cint n; 

Cint nuin[] ; 

Casptype value[]; 

} Cflaglist; 

The n element of the flags argument determines how many flags are to be set. The num 
array of the flags argument determines which flags are to be set. Flag numbers are provided 
in Table 4-2. Finally, the value array of the flags argument determines the values of the flags 
specified in num. If a value is assigned to INDIVIDUAL, the individual attribute functions affect 
the current attribute. If the value of index is BUNDLED, calls to individual attribute functions 
have no effect. The default bundle index is set to 1 (which initially contains the default value for 
the attributes specified in Table 4-1). The default value of all atpect source flags is INDIVIDUAL. 

ERRORS: 

5 ENOTOPOP CGI not in proper state CGI shall be in state VDOP, VSOP, or VSAC. 
Table 4-2: Attribute Source Flag Numbers 


Flag Attribute 

Flag Attribute 

0 line type 

1 line width 

2 line color 

3 marker type 

4 marker width 

5 marker color 

6 interior style 

7 hatch index 

8 pattern index 

9 fill color 

10 perimeter type 

11 perimeter width 

12 perimeter color 

13 text font index 

14 text precision 

15 character expansion factor 

16 character spacing 

17 text color 


4.1.2. define_bundle_index (Cdefbundix^ 


Cerror defino_bundle_index(index,entry) 

Cint index; /* entry in attribute environment table */ 

Cbunatt ‘entry; /* now attribute values */ 

define_bundle_index is a nonstandard function which defines an entry in the bundle table. 
The type Cbunatt is a structure which contains elements corresponding to all the attributes. If 
the contents of a bundle table entry are changed, all subsequently drawn primitives use the infor¬ 
mation in the new entry. You should keep this fact in mind if you are designing display list 
traversal algorithms using SunCGI. 
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typedef struct { 

Clintype llne_typo; 

Cfloat line_wldth; 

Cint lino_color; 

Cmartype marker_typo; 

Cfloat marker_size; 

Cint marker_color; 

Cintertype interior_style; 

Cint hatoh_index; 

Cint pattern_index; 

Cint fill_color; 

Clintype perimeter_type; 

Cfloat perimeter_width; 

Cint perimeter_color; 

Cint text_font; 

Cprectype text^recision; 

Cfloat character_expansion; 

Cfloat character_spacing; 

Cint text_color; 

} Cbunatt; 


ERRORS: 

5 ENOTOPOP CGI not in proper state CGI shall be in state VDOP, VSOP, or VSAC. 

31 EBBDTBDI Bundle table index out of range. 


4.2. Line Attributes 

SunCGl provides for specifying the style, width and color of lines which constitute poly/ifie«, 
rectangles, circular arcs, and elliptical arcs. The functions do not affect the drawing of the per¬ 
imeter of polygon#, rectangles, circles, or ellipses. The attributes of the perimeters of solid 
objects are set by the perimeter functions. 


4-2.1. polyline_bundle_index ^Cpolylnbundix^ 


Cerror polyline_bundle_index(index) 

Cint index; /* polyline bundle index */ 

polyline_bundle_index sets the current polyline bundle index to the value of index. The 
contents of the polyliT:e_bundle_index are line type, line width and Itne color. The line 
width specification mode and the line_endstyle function are not included in the polyline 
bundle. If index is not defined, an error is generated, and the polyline_bundle_index does 
not change. If the ASF’s for any of these attributes is set to BUNDLED, the current values of these 
attributes are set to the contents of the bundle. 

ERRORS: 

5 ENOTOPOP CGI not in proper state CGI shall be in state VDOP, VSOP, or VSAC. 
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33 EBADLINX Polyline index is invalid. 
4 . 2 . 2 . line_type ^Clntype^ 


Cerror line_type (ttyp) 

Cllntype ttyp; /* style of lino */ 

The styles of line offered are SOLID, DASHED, DOTTED, DASHED_DOTTED. and DASH_DOT_DOTTED. 
The default line style is SOLID. The actual representation of a line on the screen is affected by 
the line endstyle. 

ERRORS: 

5 ENOTOPOP CGI not in proper state CGI shall be in state VDOP, VSOP, or VSAC. 
30 EBTBUNDL ASF is BUNDLED. 

4.2.3. line_endstyle fClnendstyley 


Cerror llne_endstylo (ttyp) 

Cendstyle ttyp; /* style of line */ 

1 ino_endsty 1 e determines how a textured (non-SOLID) line terminates. The three values 
which ttyp can assume are NATURAL, POINT, and BESTJFIT. If the endstyle selected is NATURAL, 
the last component of the line texture (for example, a dash or a dot) which can be completely 
drawn is drawn. Blank space at the end of the line may cause the dine to not appear as long as 
specified by the starting and ending coordinates. If the endstyle selected is POINT, the last point 
of the line is drawn whether it is appropriate or not. In this case, the endpoints of the line 
always appear on the screen. If the endstyle selected is BEST_FIT, the last point is always drawn 
but is extended as far back as the last space if appropriate. However, the BESTJPIT endstyle may 
shorten the space between the last element of the line and the element preceding the last ele¬ 
ment by one in order to guarantee that the line ends on a drawn point. The default endstyle is 
BEST_FIT. 

ERRORS; 

5 ENOTOPOP CGI not in proper state CGI shall be in state VDOP, VSOP, or VSAC. 

4.2.4. line_widith_specification_mode (Clnwidthspecmode^ 


Cerror lino_width_specifloation_mode(mode) 

Cspecmode mode; /* pixels or percent */ 

line_width_specificatiori_mode allows the line^width to be specified in pixels or as a per¬ 
centage of VDC Space according to the value of mode (which can either be ABSOLUTE or SCALED). 
If the line width specification mode is changed from ABSOLUTE to SCALED, the change in the line 
width will probably be dramatic. 
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If multiple view surfaces are open, the line width is calculated on the basis of the first view sur¬ 
face opened. 

ERRORS: 

5 ENOTOPOP CGI not in proper state CGI shall be in state VDOP, VSOP, or VSAC. 
4 . 2 . 5 . line_width ^Clnwidth^ 


Cerror lino_wldth(index) 

Cfloat index; /* line width */ 


line_width determines the width of the lines composing polylines, circular arcs, etc. If the 
line_width^ 9 pecificatton_mode is SCALED, index is expressed in percent of VDC Space and if the X 
and Y dimensions are different, the width is calculated on the basis of the range of the x- 
coordinate of VDC space. If the parameter setting would result in a line less than one pixel wide, 
the line width is displayed as one pixel wide. The default line mdth is 0.0 (SCALED). 


ERRORS: 

5 ENOTOPOP 
30 EBTBUNDL 
34 EBDWIDTH 

4.2.6. line_color 


CGI not in proper state CGI shall be in state VDOP, VSOP, or VSAC. 
ASF is BUNDLED. 

Width must be nonnegative. 

(CXtlcoIot ) 


Cerror line_color(Index) 

Cint Index; /* line color */ 

line_color resets the color of the lines, index selects an entry in the color lookup table. The 
default value of index Is 1. 


ERRORS: 


5 

ENOTOPOP 

CGI not in proper state CGI shall be in state VDOP, VSOP, or VSAC. 

30 

EBTBUNDL 

ASF is BUNDLED. 

35 

ECINDXLZ 

Color index is less than zero. 

36 

EBADCOLX 

Color index is invalid. 

4.3. 

Polymarker 

Attributes 


The type, size and color of markers (the components of polymarkers) are controlled by the fol¬ 
lowing functions. 
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4.3.1. polymarker_bundle_index ^Cpolymkbundix^ 


Cerror polyinarker_bundlo_index (index) 

Cint index; /* polymarker bundle index */ 

polymarker_bundle_index sets the current polymarker bundle index to the value of index. 
The contents of a polymarker_bundle are marker type, marker width and marker color. 
The marker tize specification mode function is not included in the polymarker bundle. If index 
is not defined, an error is generated, and the polymarker_bundle_index does not change. If the 
ASF’s for any of these attributes is set to BUNDLED, the current values of these attributes are set 
to the values of the corresponding attribute in the bundle. 

ERRORS: 

5 ENOTOPOP CGI not in proper state CGI shall be in state VDOP, VSOP, or VSAC. 
37 EBADMRBCX Polymarker index is invalid. 

4.3.2. marker_type (Crnktypej 


Cerror marker_typo (ttyp) 

Cmartypo ttyp; /* stylo of marker */ 

marker_type sets the marker type to one of five marker types DOT, PLUS, ASTERISK, CIRCLE, or 
X. Be sure to use an argument of Cmartypo and not Cint. 

ERRORS: 

5 ENOTOPOP CGI not in proper state CGI shall be in state VDOP, VSOP, or VSAC. 
30 EBTBUNDL ASF is BUNDLED. 

4.3.3. marker_size_specification_mode ^Cmksizespecmode^ 


Cerror marker_size_specification_modo(mode) 

Cspecmode mode; /* pixels or percent */ 

marker_size_specification_mode allows the marker_size to be specified in pixels or as a 
percentage of VDC Space according to the value of mode (which can either be ABSOLUTE or 
SCALED). 

If multiple view surfaces are open, the marker size is calculated on the basis of the first view sur¬ 
face opened. 

ERRORS: 

5 ENOTOPOP CGI not in proper state CGI shall be in state VDOP, VSOP, or VSAC. 
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4.S.4- marker_size (Cxaksize) 


Cerror marker_Blze(index) 

Cfloat Index; /• marker size */ 

marker_size sets the size of the marker height and marker width, index is expressed in per¬ 
cent of VDC Space. The default marker size is 4 percent of VDO space. If the marker size 
becomes very small, markers of all types are displayed as points. An error is detected if index is 
negative. 

ERRORS: 

5 ENOTOPOP CGI not in proper state CGI shall be in state VDOP, VSOP, or VSAC. 
38 EBADSIZE Size must be nonnegative. 


4 .S. 5 . marker_color (Cmkcolor^ 


Cerror marker_color(index) 

Cint index; /* marker color */ 


marker_color resets the color of the markers, index selects an entry in the color lookup table. 
An error is detected if index is not between 0 and 255. 


ERRORS: 

5 ENOTOPOP 
30 EBTBUNDL 

35 ECINDXLZ 

36 EBADCOLX 


CGI not in proper state CGI shall be in state VDOP, VSOP, or VSAC. 
ASF is BUNDLED. 

Color index is less than zero. 

Color index is invalid. 


4.4. Solid Object Attributes 

The solid object attribute functions describe how all solid object primitives are filled (colored-in). 
There are three sets of solid object attribute functions: 

fill area attributes 

determine the general method for ‘coloring-in’ solid geometrical objects. 
pattern attributes 

determines a pixel array for filling a polygon if the fill style is set to PATTERN. 
perimeter attributes 

determine how the edge of a geometrical object is displayed if the perimeter visibility 
is ON. 
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4 . 4 . 1 . Fill Area Attributes 

The fill area attribute functions determine the general method for drawing polygons, filled rec¬ 
tangles, circles, and ellipses. 


4 . 4 . 1 . 1 . fill_area_bund.le_index ^Cflareabundix/ 


Cerror flll_area_bundle_index(index) 

Cint index; /* fill area bundle index */ 

fill_area_bundle_index sets the current fill area bundle index to the value of index. The 
contents of the fill_area_bundle are interior style, fill color, hatch index, pattern index, 
perimeter type, perimeter width and perimeter color. The perimeter width specification mode 
and the pattern attributes are not included in the definition of the filLarea bundle. If index is 
not defined, an error is generated, and the filL.areaJbundle_index does not change. If the ASF’s 
for any of these attributes is set to BUNDLED, the current value of the attribute is set to the 
value of the corresponding attribute in the bundle. 

ERRORS: 

5 ENOTOPOP CGI not in proper state CGI shall be in state VDOP, VSOP, or VSAC. 

39 EBADFABX Fill area index is invalid. 

4.4-l.S. interior_st:yle ^Cintstyle^ 


Cerror interior_style(istyle,perimvis) 

Cintertype istyle; /* fill style */ 

Cflagtype perimvis; /* perimeter visibility */ 

interior_style sets the fill style for solid objects to either HOLLOW, SOLIDI, PATTERN, or 
HATCH. If the fill style is set to SOLIDI, the solid object is filled with the current fill color. How¬ 
ever, the appearance of the solid object on the screen depends on the drawing mode. If istyle is 
set to PATTERN or HATCH, the solid object is filled with the current PATTERN or HATCH style. 
The PATTERN and HATCH styles are explained in the pattern attributes section. The default fill 
style is HOLLOW. 

interior_style also determines whether the perimeter of the solid object is visible according 
to the value of perimvis (which must be ON or OFF). If perimvis is OFF, the perimeter attributes 
have no effect. The default value of perimeter visibility is ON. 

Be careful when using the interior style function to explicitly specify the perimvis argument. If 
you do not specify it, or set it to OFF, the geometrical output primitive may not be displayed 
because the interior style is HOLLOW. 


ERRORS: 

5 ENOTOPOP CGI not in proper state CGI shall be in state VDOP, VSOP, or VSAC. 
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fill_color ^Cflcolor^ 


Cerror fill_color(color) 

Cint color; /* color for solid object fill */ 

fill_color determines the color for filling solid objects, if the fiU style is not set to HOLLOW. 

The default fill style is HOLLOW, so changing the fill color will not have an effect without chang¬ 
ing the interior style first. 

The default fill color is 1. 


ERRORS: 


5 

ENOTOPOP 

CGI not in proper state CGI shall be in state VDOP, VSOP, or VSAC. 

35 

ECINDXLZ 

Color index is less than zero. 

36 

EBADCOLX 

Color index is invalid. 

lit 

Pattern Attributes 


Geometrical primitives can be filled with two dimensional arrays of color values called patterns. 
SunCGI supports pre-defined as well as user-defined patterns. The definition of patterns is 
stored in the pattern table. Each entry in the pattern table consists of a two-dimensional array 
of color values and the X and Y dimensions of the array. The starting position (lower left-hand 
corner) of the pattern is determined by the pattern reference point. 

Two types of patterns are available; PATTERNS and HATCHes. PATTERNS can be scaled and 
translated. HATCHes can’t and simply fill the geometrical output primitives with pixel arrays. 


4.4.S.I. hatch_index (Chatchix^ 


Cerror hatch^index(index); 

Cint index; /* index in the pattern table bound to HATCH */ 


hatch_index determines which index in the pattern table is used to fill solid objects when the 
fill style is set to HATCH. The default hatch index is 1. An error is generated if index points to 
an undefined entry in the pattern table. 


ERRORS: 

5 ENOTOPOP 
30 EBTBUNDL 

42 ESTYLLEZ 

43 ENOPATNX 


CGI not in proper state CGI shall be in state VDOP, VSOP, or VSAC. 
ASF is BUNDLED. 

Style (pattern or hatch) index is less than zero. 

Pattern table index not defined. 
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4 . 4 . 2 . 2 . pattern_index ^Cpatix^ 


Cerror pattern_index(index); 

Clnt index; /* index in the pattern table bound to PATTERN */ 

pattern_index determines which index in the pattern table is used to fill solid objects when 
the fill style is set to PATTERN. pattern_index also determines the pattern which is used by 
drawing mode. The default pattern index is 2. An error is generated if index points to an 
undefined entry in the pattern table. Note that pattern_index 0 is not defined. 


ERRORS: 


5 

ENOTOPOP 

CGI not in proper state CGI shall be in state VDOP, VSOP, or VSAC. 

30 

EBTBUNDL 

ASF is BUNDLED. 

42 

ESTYLLEZ 

Style (pattern or hatch) index is less than zero. 

43 

ENOPATNX 

Pattern table index not defined. 


4.4-S-3. pattern_table (tpattablo^ 

Cerror pattern_table(index,m,n,colorind) 

Cint index; /* entry in table */ 

Cint m,n; /* nxunber of rows and colxunns */ 

Cint *colorind; /* array containing pattern */ 

pattern_tablo defines an entry in the pattern table, index defines the entry in the table 
(which must be less than 10). An error is generated if index is outside the bounds of the pattern 
table, m and n define the height and width of the pattern (in pixels). The array pointed to by 
the argument colorind contains the actual pattern. All nonzero entries in colorind are set to 1. 
Pattern 1 is initially defined to be a three-by-three matrix which is set to zero at the corners and 
one elsewhere. Pattern 1 produces simple cross-hatching. Pattern 2 (which produces a polka-dot 
pattern) is initially defined to be a three-by-three matrix which is set to 1 at the center and 0 
elsewhere. The maximum number of elements in a pattern is 256. 


ERRORS: 


5 

ENOTOPOP 

CGI not in proper state CGI shall be in state VDOP, VSOP, or VSAC. 

40 

EPATARTL 

Pattern array too large. 

41 

EPATSZTS 

Pattern size too small. 

42 

ESTYLLEZ 

Style (pattern or hatch) index is less than zero. 

44 

EPATITOL 

Pattern table index too large. 


4 . 4 ‘^‘ 4 ' pattern_reference_point (tpatrefpt^ 
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Cerror pattern_reference_point(begin) 

Ccoor *begin; 

pattern_reference_poin-t defines the point in VDC Space where the pattern box begins. 
begin determines the offset of the pattern, pattern^reference^point has no effect if the interior 
style is set to HATCH. The lower left-hand corner of the pattern box is determined by begin. The 
pattern is conceptually replicated over all of VDC Space — the begin point provides for fine posi¬ 
tioning of the pattern. The default pattern reference point is (0,0). 

ERRORS: 

5 ENOTOPOP CGI not in proper state CGI shall be in state VDOP, VSOP, or VSAC. 


pattern_size fcpatsizey 


Cerror pattern_sIze(dx,dy) 

Cint dx.dy; /* size of pattern in VDC Space */ 

pattern_size defines the size of the pattern array in VDC coordinates, dx and dy determine 
the size of an element of the pattern in VDC Space. pattern_size therefore allows you to ‘stretch’ 
the pattern to a certain size. If dx or dy would result in pattern elements less than one pixel 
wide, an error is generated and the pattern size is set m pixels by n pixels.*® If the pattern size is 
larger than the bounds of screen space, the effective pattern size is the size of VDC Space. The 
default pattern size is 300,300. 

ERRORS: 

5 ENOTOPOP CGI not in proper state CGI shall be in state VDOP, VSOP, or VSAC. 
4.4 3 . Perimeter Attributes 

As mentioned previously, control of the drawing of the borders of solid objects is under the con¬ 
trol of the perimeter attribute functions, not the line attribute functions. However, the two sets 
of functions perform the same tasks. Perimeter attribute functions have no effect if the perime¬ 
ter visibility is set to OFF. The perimeter attributes are essentially the same as the line attri¬ 
butes except that they affect the borders of solid attributes. Which attributes affect which prim¬ 
itives may become ambiguous when the interior style is set to HOLLOW. 


4.4-S.l. perimeter_type (fcperimtype^ 


Cerror perimoter_type (ttyp) 

Clintype ttyp; /* stylo of perimeter */ 

The styles of perimeter offered are SOLID, DASHED, DOTTED, DASHED_DOTTED, and 
DAS H D OT DOTTED. The default perimeter style is SOLID. The actual representation of a 


m and n are obtained from the pattern table. 
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perimeter is effected by drawing mode as well as the perimeter style. Notice that there is no 
ending style for perimeter. The endstyle is controlled by the line endstyle function. 

ERRORS: 

5 ENOTOPOP CGI not in proper state CGI shall be in state VDOP, VSOP, or VSAC. 
30 EBTBUNDL ASF is BUNDLED. 

periineter_width ^Cperimwidth/ 


Cerror perimeter_width(index) 

Cfloat index; /* perimeter width */ 

perimeter_width determines the width of the perimeters of solid objects. Index can be 
expressed in percent of VDC Space or pixels. If the perimeter width specification mode is set to 
SCALED and the x and y dimensions are different, the perimeter width is calculated on the basis 
of the range of the x-coordinate of VDC space. If the parameter setting would result in a perime¬ 
ter less than one pixel wide, the perimeter width is displayed as one pixel wide. The default per¬ 
imeter width is 0.0 (SCALED). 

ERRORS: 

5 ENOTOPOP CGI not in proper state CGI shall be in state VDOP, VSOP, or VSAC. 
30 EBTBUNDL ASF is BUNDLED. 

34 EBDWIDTH Width must be nonnegative. 

4.4-3 perimet;er_width_specificat;ion_mode (fcperimwidthspecmodey 


Cerror perimeter_width_specificatlon_mode(mode) 

Cspecmode mode; /* pixels or percent */ 

perimeter_width_speci fication_mode allows the perimeter_width to be specified in 
pixels or as a percentage of VDC Space according to the value of mode (which can either be 
ABSOLUTE or SCALED). If the perimeter width specification mode is changed from ABSOLUTE to 
SCALED, the change in the line width will probably be dramatic. 

If multiple view surfaces are open, the perimeter width is calculated on the basis of the first view 
surface opened. 

ERRORS: 

5 ENOTOPOP CGI not in proper state CGI shall be in state VDOP, VSOP, or VSAC. 


4.4.3.4‘ perimeter_color (tporimcolor^ 


Cerror perimeter_color(Index) 

Cint Index; /* perimeter color */ 
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periineter_color resets the color of the perimeters, index selects an entry in the color 
lookup table. The default value of index is 1. An error is detected if index is not between 0 and 


255. 

ERRORS: 


5 

ENOTOPOP 

CGI not in proper state CGI shall 

30 

EBTBUNDL 

ASF is BUNDLED. 

35 

ECINDXLZ 

Color index is less than zero. 

36 

EBADCOLX 

Color index is invalid. 


be in state VDOP, VSOP, or VSAC. 


4.5. Text Attributes 

SunCGI provides a variety of functions for determining how text is written to the screen. The 
most important text attribute is text precision. If text precision is set to STRING, firmware char¬ 
acters are used. The fonts, size, spacing, and alignment of firmware are more limited than char¬ 
acters drawn with text precision set to a value other than STRING. Therefore, calls to text attri¬ 
bute functions regulating these aspects of text drawing have no effect when text precision is set 
to STRING. 

4-5.1. text_bundle_index ^Ctextbundixj 


Cerror text_bundle_index(index) 

Cint index; /* text bundle index */ 

text_bundle_index sets the current text bundle index to the value of index. The contents of 
the text bundle index are text font text precision, character expansion factor, character spacing, 
and text color. The character height, character orientation, character path, text alignment and 
fixed font are not included in the definition of the text bundle. If index is not defined, an error is 
generated, and the text bundle index does not change. If the ASF’s for any of these attributes are 
set to BUNDLED, the current values of these attributes are set to the contents of the bundle. 

ERRORS: 

5 ENOTOPOP CGI not in proper state CGI shall be in state VDOP, VSOP, or VSAC. 

45 EBADTXTX Text index is invalid. 

4-5.2. text_precision fCtextprec,^ 


Cerror text_precision (ttyp) 

Cpreotype ttyp; /* text type */ 

text_precision controls the type of text displayed, ttyp can assume one of three values: 
STRING, CHARACTER, or STROKE. If the text precision is set to STRING, the firmware character 
set is used. 
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Firmware characters cannot be scaled or rotated. 

Characters are clipped, but not in parts (that is, if any portion of the character exceeds the clip¬ 
ping boundary the whole character is clipped). If the text precision is set to CHARACTER, 
software generated characters are employed. All text attributes have a visible effect on software 
generated characters, but according to the standard, text drawn with CHARACTER precision are 
not clipped in parts. However, in SunCGI, characters are clipped in parts. If the text precision 
is set to STROKE, the CHARACTER precision capabilities are enabled and characters are clipped in 
parts. The default text precision is STRING. 

ERRORS: 

5 ENOTOPOP CGI not in proper state CGI shall be in state VDOP, VSOP, or VSAC. 
30 EBTBUNDL ASF is BUNDLED. 


4.5.3. character_set_index (debarsetixj 



Cerror character_set_index(index) 

Cint index; /* font set */ 

character_set_index selects a set of fonts. Although SunCGI supports this function, only 
set number 1 is defined. Calls to ckaracter^set_index with index assigned to a value other than 1 
are ignored. 

ERRORS: 

5 ENOTOPOP CGI not in proper state CGI shall be in state VDOP, VSOP, or VSAC. 


4.5.4- text_font_index (Ctextfontix^ 


Cerror text_font_index(index) 

Cint index; /* font */ 

text_font_index resets the current font. A list of available fonts and their availability when 
text precision is set to STRING is given in Table 4-3, A warning about the SYMBOL font: 
undefined characters are displayed as bugs (the six-legged kind). The default font is STICK. 

ERRORS: 

5 ENOTOPOP CGI not in proper state CGI shall be in state VDOP, VSOP, or VSAC. 
30 EBTBUNDL ASF is BUNDLED. 

47 ETXTFLIN Text font is invalid. 
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Table 4-3: Available Fonts 


Font 

Available in String Precisionf 

ROMAN 

YES 

GREEK 

YES (displayed as STICK font) 

SCRIPT 

YES 

OLDENGLISH 

NO 

STICK 

YES 

SYMBOLS 

NO 


4 . 5 . 5 . character_expansion_factor ^Ccharexpfac^ 


Cerror character_expanslon_factor(efac) 

Cfloat efac; /* width factor */ 

character_expansion_fac'tor determines the width-to-height ratio of characters. If efac is 
greater than 1 the characters appear fatter than they are wide. If efac is less than 1 the charac¬ 
ters appear slimmer than they are wide. The default character expansion factor is 1.0. An error 
is generated if efac is less than .01 or greater than 10. 

ERRORS: 

5 ENOTOPOP CGI not in proper state CGI shall be in state VDOP, VSOP, or VSAC. 
30 EBTBUNDL ASF is BUNDLED. 

48 ECEXFOOR Expansion factor is out of range. 

4 . 5 . 6 . character_spacing ^Ccharspacing^ 


Cerror character_spacing(spcratlo) 

Cfloat spcratlo; /* spacing ratio */ 

character_spacing sets the spacing between characters based on the height of the charac¬ 
ters. The amount of space between characters is obtained by multiplying the character height 
by spcratio. The default character spacing factor is 0.1. An error is generated if spcratio is less 
than .01 or greater than 10, 

ERRORS: 

5 ENOTOPOP CGI not in proper state CGI shall be in state VDOP, VSOP, or VSAC. 
30 EBTBUNDL ASF is BUNDLED. 

48 ECEXFOOR Expansion factor is out of range. 
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character_height: (tcharheight^ 

Cerror character_Jieight (height) 

Clnt height; /* height in VDC */ 

The character_height function determines the height of text in VDC coordinates. The height is 
defined as the distance from the top to the bottom of the character. 

Notice that changing the character height implicitly changes the character apacing. 

The default character height is 1000. This may result in huge characters if VDC Space is reset 
from its default range (0-32767). If the X and Y dimensions of VDC Space are different, the 
height is calculated on the basis of the range of the x-coordinate of VDC space. 


ERRORS; 


5 

ENOTOPOP 

CGI not in proper state CGI shall be in state VDOP, VSOP, or VSAC, 

30 

EBTBUNDL 

ASF is BUNDLED. 

49 

ECHHTLEZ 

Character height is less than or equal to zero. 

4 . 5 . 8 . 

f ixed_font: 

(C fixed font^ 


Cerror fixed_font (index) 

Cint index; /* fixed or variable width characters */ 

fixed_font is a nonstandard CGI function ’which allows characters to be of fixed or variable 
size. If index is nonzero, the characters are of uniform size, otherwise the characters are packed 
proportional to their actual sizes. If the character precision is STRING, this function has no 
effect. 

ERRORS: 

5 ENOTOPOP CGI not in proper state CGI shall be in state VDOP, VSOP, or VSAC. 
4 . 5 . 9 . text_color (Ctextcolor^ 


Cerror text_color(index) 

Cint index; /* color */ 

■text_color resets the color of the text, index selects an entry in the color lookup table. The 
default value of index is 1. An error is detected if index is not between 0 and 255. 

ERRORS: 

5 ENOTOPOP CGI not in proper state CGI shall be in state VDOP, VSOP, or VSAC. 
30 EBTBUNDL ASF is BUNDLED. 

35 ECINDXLZ Color index is less than zero. 
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36 EBADCOLX Color index is invalid. 

4.5.10. character_orientation ^Ccharorientation^ 


Cerror character_orientatlon (xup,yup,xbase,ybase) 

Cfloab xup.yup,xbaso,ybase; /* character base and character up vectors */ 

character_orientation specifies the skew and direction of text. The left side of the char¬ 
acter box lies on an invisible line called the character up vector whose slope is determined by 
xbase and xup. The bottom of the character box lies on an invisible line called the character 
hate vector whose slope is determined by ybase and yup. 

If the character up vector and the character base vector are not orthogonal, the text is distorted. 

Calls to character_orientation have no effect if text precision is set to STRING. The 
default values for the character up vector and the character base vector are xup =1.0, yup =1.0, 
xbase =0.0, and j/6ase=0.0. 

The character up vector and the character base vector influence the character path and the char¬ 
acter alignment. For example, if xJose=-1.0 and the character path is RIGHT, the text is written 
to the left. 

ERRORS: 

5 ENOTOPOP CGI not in proper state CGI shall be in state VDOP, VSOP, or VSAC. 

50 ECHRUPVZ Length of character up vector or character base vector is zero. 

4.5.11. character_path fCcharpath^ 


Cerror character_path(path) 

Cpathtype path; /* text direction */ 

The character^path function respecifies direction that text is written. The four possible direc¬ 
tions are RIGHT, LEFT, UP, and DOWN. The actual effect of character ..path depends on the char¬ 
acter up vector and the character base vector. RIGHT specifies that the text is written in the 
direction of the character base vector. For example, if the direction of the character base vector 
points left instead of right (xup =—1.0 instead of 1.0), the text will be written right-to-left instead of 
left-to-right which is the usual interpretation of RIGHT. LEFT specifies that the text is written in 
the opposite direction of the character base vector. The character up vector and character base 
vector essentially change functions when the character direction is set to UP or DOWN. UP 
specifies that the text is uriffcn in the direction of the character up vector. DOWN specifies that 
the text is written in the opposite direction of the character up vector. The default character 
path is RIGHT. 

ERRORS: 

5 ENOTOPOP CGI not in proper state CGI shall be in state VDOP, VSOP, or VSAC. 
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4.5.12. textual ignment ^Ctextalign^ 


Cerror text_allgnment (halign,valigii,hcalind,vcalind) 

Chaligntypo halign; /* horizontal alignment type */ 

Cvaligntype valign; /* vertical alignment type */ 

Cfloat hcalind,vcalind; /* continuous alignment indicators */ 

text_alignment determines where the text is positioned relative to the starting point 
specified by the cl argument of the text or vdm_text function. The value of the halign 
argument (which must be one of LFT, CNTER, RGHT, NRMAL, CNT) determines where the charac¬ 
ter is placed in relation to the x component of the starting coordinate of the text position 
(specified by the cl argument of text). If the value of halign is LFT, the horizontal position of the 
text will begin at the left edge of the box enclosing the text. Similarly, if the value of halign is 
RGHT, the horizontal position of the text will begin at the right edge of the box enclosing the 
text. If the value of halign is CTR the horizontal position of the text will begin equidistant from 
the right and the left edges of the text box. NRML assigns the alignment based on the value of 
the character path (see Table 4-4). If the value of halign is CNT (continuous) the horizontal posi¬ 
tion of the text is determined by the argument hcalind. In this case, the text will begin hcalind 
percent of the width of the text box from the left edge of the character box. The default value 
of halign is NRML. 

The value of the valign argument (which must be one of TOP, CAP, HALF, BASE, BOTTOM, NOR¬ 
MAL, CONT) specifies where the character is placed in relation to the y component of the text 
position. If the value of valign is TOP, the vertical position of the text will begin at the top edge 
of the character box. If the value of valign is CAP, the vertical position of the text will begin at 
the cap line of the character.*^ Similarly, if the value of valign is BOTTOM, the vertical position 
of the text will begin at the bottom edge of the character box. If the value of valign is BASE, the 
vertical position of the text will begin at the baseline of the character.^^ If the value of valign is 
HALF the vertical position of the text will begin equidistant from the top and the bottom edges 
of the character box. NORMAL assigns the alignment based on the value of the character path 
(see Table 4-4). If the value of valign is assigned to CONT (continuous), the vertical position of 
the text is determined by the argument vcalind and will begin vcalind percent of the distance 
from the bottom edge of the character box. The default value of valign is NORMAL. 


The cap line is defined as the invisible line corresponding to the top of the average character within a 

font. 

The baeeline is defined as the invisible line corresponding to the bottom of the average character 
within a font. The baeeline does not necessarily correspond to the bottom of a character. For example, a 
the tail of a lower-case g extends below the baseline. 
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Table 4-4: Normal Alignment Values 


Character 

Path 

Horizontal 

Normal 

Vertical 

Normal 

RIGHT 

LEFT 

BASELINE 

LEFT 

RIGHT 

BASELINE 

UP 

CENTER 

BASELINE 

DOWN 

CENTER 

TOP 


ERRORS: 

5 ENOTOPOP CGI not in proper state CGI shall be in state VDOP, VSOP, or VSAC. 


4.6. Color Attributes 

SunCGI supports only one color specification mode — INDEXED. Index color specification mode 
means that the red, green, and blue values (hereafter referred to as rgb values) are obtained from 
a table known as the color lookup table. The initial values of the color lookup table are provided 
in Table 4-5. If the device is black and white, nonzero color values are displayed as black; zero 
is displayed as white. 

Table 4-5: Default Color Lookup Table 


Index 

Color 

0 

black 

1 

red 

2 

yellow 

3 

green 

4 

cyan 

5 

blue 

6 

magenta 

7 

white 


4.6.1. color_table (Ccotable^ 


Cerror color_table(istart.clist) 

Cint istart; /* starting address */ 

Ccentry *clist; /* color triples and number of entries */ 

color_table resets color lookup table entries. The color lookup table is a set of 258 rgb 
entries. The argument ittart determines the first entry in the color lookup table to be modified. 
The argument clitt contains the color information for entry iotart in terms of triples of values of 
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numbers ranging between 0 and 255. The last field of cUst reports how many entries are 
modified. An error is generated if either the indices to the color lookup table are out of range. 

ERRORS: 

5 ENOTOPOP CGI not in proper state CGI shall be in state VDOP, VSOP, or VSAC. 

35 ECINDXLZ Color index is less than zero. 

36 EBADCOLX Color index is invalid. 

4.7. Inquiry Functions 

The attribute inquiry functions permit examination of the current attributes. Attributes are 
reported in groups corresponding to the class of output primitive which they modify. The argu¬ 
ment to each inquiry function has its own structure type which has an element for each of the 
individual attributes (see Appendix D). 


4.7-1- inquire_line_attributes (Cqlnatts^ 


Clinatt *inquire_line_attributes0; 

/* pointer to line attribute structure */ 

inquire_line_attributes reports the current line ttyle, line width, line color, and 
polyline_bundle_index in the appropriate elements of the returned value of the function. 

typedef struct •{ 

Clintypo stylo; 

Cfloat width; 

Cint color; 

Cint index; 

} Clinatt; 

Since inquire_line_attributes does not return an error, errors are only reported in 
INTERRUPT mode. 

ERRORS: 

5 ENOTOPOP CGI not in proper state CGI shall be tn state VDOP, VSOP, or VSAC. 
4 . 7 .S. inquire_inarker_attributes /Cqmkatts^ 


Cmarkatt *inquire_marker_attributes(); 

/* pointer to marker attribute structure */ 

inquiro_markor_attributes reports the current marker ttyle, marker width, marker color, 
and polyiiiarkor_buridle_index in the appropriate elements of the returned value of the 
function. 
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typedef struct •{ 

Cmartypo type; 

Cfloat size; 

Cint color; 

Cint index; 

} Cmarkatt; 

Since inquire_marker_attributes does not return an error, errors are only reported in 
INTERRUPT mode. 

ERRORS: 

5 ENOTOPOP CGI not in proper state CGI shall be in state VDOP, VSOP, or VSAC. 
4 . 7 . 5 , inquire_fill_area_attributes /tqflareaatts^ 


Cfillatt *inquire_fill_area_attributes(); 

/* pointer to fill area attribute structure */ 

The current interior ttyle, perimeter visibility, fill color, hatch index, pattern index, fill area bun¬ 
dle index, perimeter style, perimeter width, and perimeter color can be obtained by using the 
inquire_fill_attributes function. 

typedef struct -f 

Cintertype style; 

Cflagtype visible; 

Cint color; 

Cint hatch_index; 

Cint pattern_lndex; 

Cint index; 

Clintype pstyle; 

Cfloat pwidth; 

Cint pcolor; 

} fillatt; 

Since inquire_fill_area_attributes does not return an error, errors are only reported 
in INTERRUPT mode. 

ERRORS: 

5 ENOTOPOP CGI not in proper state CGI shall be in state VDOP, VSOP, or VSAC. 

4 . 7 . 4 . inquire_pattern_attributes ^Cqpatatts^ 

Cpatternatt *inquire_pattern_attributes(); 

/* pointer to pattern attribute structure */ 

inquire_pattern_attributes reports the current pattern index, row count, column count, 
color list, pattern reference point, and pattern size. 
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typede f struct •{ 

Cint cur_index; 

Cint row; 

Cint column; 

Cint *colorlist; 

Ccoor ‘point; 

Cint dx; 

Cint dy; 

} patternatt; 

Since inquire_pattern_attributes does not return an error, errors are only reported in 
INTERRUPT mode. 

ERRORS: 

5 ENOTOPOP CGI not in proper state CGI shall be in state VDOP, VSOP, or VSAC. 


J^.1.5. inquire_text_attributes ^Cqtextatts^ 




Ctextatt *inquire_text_attributes0; 

/* pointer to text attribute structure */ 

inquire_text_attributes reports the current /oof set, text bundle index, font, text prect- 
sion, character expansion factor, character spacing, text color, character height, character base 
vector, character up vector, character path, and text alignment. 

typede f struct ■{ 

Cint fontset; 

Cint index; 

Cint current_ font; 

Cprectype precision; 

Cfloat exp_factor; 

Cfloat space; 

Cint color; 

Cint height; 

Cfloat basex; 

Cfloat basey; 

Cfloat upx; 

Cfloat upy; 

Cpathtype path; 

Chaligntype halign; 

Cvaligntype valign; 

Cfloat hcalind; 

Cfloat vcalind; 

)• textatt; 

Since inc[uire_text_attributes does not return an error, errors are only reported in 
INTERRUPT mode. 

ERRORS: 

5 ENOTOPOP CGI not in proper state CGI shall be in state VDOP, VSOP, or VSAC. 
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J^.1.6. inquire_aspect_source_flags ^Cqasfsj 


Cflagllst *inquire_aspect_source_flags() 

/* pointer to text attribute structure */ 

inquire_aspect_source_f lags reports whether attributes are set individually by returning 
all of the values of the ASFs. The element n of the flaglist struct is set to 18. The definitions of 
each flag are in Table 4-2. 

typedef struct { 

Cint n; 

Cint *num; 

Casptype *value; 

} Cflagllst; 

Since inquire_aspect_source_flags does not return an error, errors are only reported in 
INTERRUPT mode. 

ERRORS: 

5 ENOTOPOP 

CGI not in proper state CGI shall be in state VDOP, VSOP, or VSAC. 



o 
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CGI describes an input device as consisting of a measure and a list of associations with triggers. 
A trigger corresponds to a physical input device such as a mouse button. A measure reports the 
current value of the device such as Xjy position for a locator device. SunCGI input functions 
apply to all classes of input devices. The classes of devices that are offered are listed in Table 5- 
1 . 


Table 5-1: Devices Offered by SunCGI 


Device Class Max. Number 

Description 

IC.CHOICE 

3 

Mouse button (trigger)^^ 

IC_LOCATOR 

4 

X, y position 

IC_STRING 

1 

Keyboard input 

IC_STROKE 

3 

Array of x, y positions 

IC.VALUATOR 

4 

Normalized x position 


When a trigger is activated, the measure of the device is reported to the application program by 
use of the event functions. 

The effect of the event functions depends on the state of the input device (see Table 5-2). Before 
an input device is initialized it is in the RELEASED state. When an input device Is first initial¬ 
ized, it is in the NO_EVENTS state. 

The measure (value) of the input device is the device-dependent information that the application 
program wants (for example, the LOCATOR returns the x,y position of the cursor. The measure 
of an input device in the NO_EATENTS state is the measure that it was initialized with. The meas¬ 
ure of an input device in the NO_EVENTS state does not change with activation of a trigger. For 
example, the measure of a LOCATOR does not change when the mouse moves. 


The measure of an input device is changed by trigger activation when the input device is in 
either the REQUEST_EJVENT, RESPOND_EVENT or QUEUEJ7VENT state. If the input device is in 
the REQUEST_EVENT state its measure is set by the first trigger activation after the 
initiate_request function is called. If the input device is in the RESPOND_EVENT state its 

The left mouse button is choice 2, the middle button is choice 3, and so on. 
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measure is set by the most recent trigger activation. Previous trigger activations are not stored. 
When an input device is in the QUEUE_EVENT state, trigger activation is buffered by the event 
queue. The event queue processes inputs in the order that they are received provided that the 
event queue is not overflowing. 


Table 5-2: States of Input Devices 


State 

Brief Description 

RELEASED 

Device not initialized. 

NO_EVENTS 

Device initialized, but unable to process events. 

REQUEST_EVENT 

Device measure set by first (and only first) trigger activation. 

RESPOND_EVENT 

Device measure settable by most recent trigger activation. 

QUEUEJEVENT 

Device able to post events on the event queue. Device measure 
settable by trigger activation when processed. 


The figure below illustrates the CGI input state model. 


Get Last Req. Input 
Await Event 



1 1 

i 1 

5 request ! 

• event « 

1 1 

1 1 

1 1 

1 1 

j respond ! 

« event [ 

1 1 

1 I 

{ queue | 

' event « 

1 1 

t 1 

1 1 

1 . j 

1 1 
— J 

1 1 

TV-IU 

I_f 

1_* 

Sample Input 

Init Request 
(Request Input, 

Enable Events cause error) 

Sample Input 
(Init Request 

Request, 

Enable Events cause error) 

trigger fires 
Sample Input 
Await Event 
(request, 

Init request cause error 


Figure 5-1: CGI Input State Model 
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In addition to reporting input to an application program, you may want to have the measure of a 
device displayed on all active view surfaces (called tracking). Tracking must be explicitly 
enabled for each device. In addition, the type of track is selectable for some input devices. 


5.1. Input Device Management 

Before input can be processed, the individual input devices must be initialized and associated 
with triggers. Input device initialization requires that at least one view surface is active. Typi¬ 
cally, the procedure for initializing an input device includes calls to the initialize_lid, 
enable_events, and associate functions which turn on an input device and permit it to 
receive input from an associated trigger (see the following example). 

{ /* initialize LOCATOR input device, get input, and close */ 

Cinrep ival; 

Clogical stat; 

Cint trig; 

ival.xypt.x = 16384; /* put cursor in the middle of the view surface */ 
ival.xypt.y = 16384; 
initialize_lld(IC_LOCATOR,l,&ival); 

associate (2,IC_LOCATOR,1); /* associate locator with mouse button 1 */ 

request_input(IC_LOCATOR, 1,5000000, &stat,&ival,Atrig) ; /* wait five seconds */ 
if (stat == TRUE) 

printf(" trigger activated at %d %d \n",ival-xypt.x,ival.xypt.y); 
else 

printf(" trigger not activated \n"); 
disable_events(IC_LOCATOR,l); /* shut device off */ 
dissociate(2,IC_L0CAT0R,1); 
releaso_input_devico (IC_LOCATOR,1); 

} 


5.1.1. iriitialize_lld (Ginitlid^ 

Cerror initialize_lid(devclass, devnum, ival) 

Cdevoff devclass; /* device type */ 

Cint devnum; /* device number */ 

Cinrep *ival; /* initial value of device measure */ 

initialize_lid (lid — Logical Input Device) must be called for an input device before it can 
be referenced by any other input function. tnitiaUzeJUd changes the state of the specified input 
device from RELEASED to N0_EVENTS. The argument develasa specifies one of the supported dev¬ 
ices, and devnum indicates the number of the device within that class. The argument ival sets 
the initial measure of the device. The structure Cinrep contains different elements for each 
type of measure. An error is generated if the device does not exist, if it is already initialized, or 
if the initial value is out of range. You must set the appropriate field of ival, or an error will 
be generated. 
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'typedef struct -{ 

Ccoor *xypt; 
Ccoorlist *points; 
Cfloat val; 

Cint choice; 

Cchar ‘string; 

J Cinrep; 


/* LOCATOR */ 

/* STROKE devices */ 
/* VALUATOR device */ 
/* CHOICE devices */ 
/* STRING device */ 


Notice that whenever a device is initialized, no associations with triggers are made. This must 
be done by having your application program call the appropriate functions. 


ERRORS; 


4 

ENOTVSAC 

CGI not in proper state: CGI shall be in state VSAC. 

80 

EINDNOEX 

Input device does not exist. 

82 

EINDALIN 

Input device already initialized.^* 

95 

EBADDATA 

Contents of input data record are invalid. 

96 

ESTRSIZE 

Length of initial string is greater than the implementation defined max- 


imum. 


5.1.2. release_input_device /trelidev^ 

Cerror release_input_dovico(dovclass, devnum) 

Cdevoff devclass; /* device typo */ 

Cint devnum; /* device number */ 

release_input_device releases all associations with triggers, and removes all pending events 
from the device from the event queue. release_input_device changes the state of the 
specified input device from NO_EVENTS to RELEIASED. An error is produced if devctass, devnum 
does not refer to an existing or initialized device. 

ERRORS: 

4 ENOTVSAC CGI not in proper state: CGI shall be in state VSAC. 

80 EINDNOEX Input device does not exist. 

81 EINDINIT Input device not initialized. 

5.1.3. f lush_everrt_queue fCflusheventqu^ 

Corr or f1ush_ovent_queuo() 

f lush_event:_queue discards ail events in the event queue. The purpose of flush^event^queue 
is to return the event queue to a stable state (NO_OFLO). This function should be used 


The Af^ standard allows initialized input devices to be re-initialized. SunCGI does not because it is 
felt that re-initialization is usually a mistake. 
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carefully to avoid throwing away mouse-ahead or type-ahead inputs. 

ERRORS: 

5 ENOTOPOP CGI not in proper state CGI shall be in either In state VDOP, VSOP, 
or VSAC. 


5 . 1 . 4 , selective_flush_of_event_queue /Gselectflusheventqu^ 

Cerror selective_flush_of_event_queue(devclass, devnum) 

Cdevoff devclass; /* device typo */ 

Cint devnum; /* device number */ 

selective_f lush_of_event_queue discards all events in the event queue which are gen¬ 
erated by the specified device. solective_f lush_of_event_queuo does not affect the 
state of the specified input device, develasi, devnum must refer to an existing or initialized dev¬ 
ice or an error is produced. However, no error is returned if no events from the specified device 
are pending. 

ERRORS: 

5 ENOTOPOP CGI not in proper state CGI shall be in either in state VDOP, VSOP, 
or VSAC. 

80 EINDNOEX Input device does not exist. 

81 EINDINIT Input device not initialized. 

5.1.5. associate ^Cassoc^ 


Cerror associate(trigger, devclass, devnum) 

Cint trigger; /* trigger number */ 

Cdevoff devclass; /* device type */ 

Cint devnum; /* device number */ 

The function asfociate links a trigger to a specific device. The trigger numbers are listed in 
Table 5-3. 


Table 5-3: Triggers Offered by SunCGI 


Trigger 

Number 

Keyboard 

1 

Mouse Button No. 1 

2 

Mouse Button No. 2 

3 

Mouse Button No. 3 

4 

Mouse Position 

5 


Multiple associations are allowed; however, some associations are not allowed (for example, 
ICJLOCATOR may not be associated with the keyboard). The interaction between an IC_STR0KE 
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device and the trigger requires some explanation. ICJSTROKE can only be linked with the mouse 
buttons. IC_STROKE returns an array of coordinates in VDC space. The first coordinate is 
entered when the mouse button is initially depressed, the last coordinate is entered when the 
mouse button is released. For IC_LOCATOR and IC_VALUATOR devices, the measure is reported 
when the mouse button is depretted. 


ERRORS: 


4 

ENOTVSAC 

CGI not in proper state: CGI shall be in state VSAC. 

80 

EINDNOEX 

Input device does not exist. 

81 

EINDINIT 

Input device not initialized. 

83 

EINASAEX 

Association already exists. 

84 

EINAIIMP 

Association is impossible. 

86 

EINTRNEX 

Trigger does not exist. 

5.1.6. 

set_default 

_trigger_associatlons ^Csdefatrigassoc^ 


Cerror set_default_trlgger_assoclations(devclass, devnum) 

Cdevoff devclass; /* device type */ 

Cint devnxim; /* device number */ 

The function set^defauH_friggcr^aetoc$ations links a trigger to a specific device. The rules for 
trigger association are the same as those for the aesociate function. The default associations are 
listed in Table 5-4. 


Table 5-4: Default Trigger Associations 


Device Claaa 

Default Trigger 

IC_LOCATOR 

5 

IC.VALUATOR 

3 

IC_STROKE 

4 

IC.CHOICE 

2 

IC_STRING 

1 


ERRORS: 


4 

ENOTVSAC 

CGI not in proper state; CGI shall be in state VSAC. 

80 

EINDNOEX 

Input device does not exist. 

81 

EINDINIT 

Input device not initialized. 

83 

EINASAEX 

Association already exists. 

86 

EINTRNEX 

Trigger does not exist. 
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5.1.7. dissociate ^Cdissocj 


Cerror dissociate(trigger, devclass, devnum) 

Cint trigger; /* trigger number */ 

Cdevoff devclass; /* device type */ 

Cint devnum; /* device number */ 

The function dittociate removes the association between a trigger and the specified device. If 
the dtsaociate function is called while there are events pending on the event queue, the pending 
events are discarded. 


ERRORS: 


4 

ENOTVSAC 

CGI not in proper state: CGI shall be in state VSAC. 

80 

EINDNOEX 

Input device does not exist. 

81 

EINDINIT 

Input device not initialized. 

85 

EINNTASD 

association does not exist. 

86 

EINTRNEX 

Trigger does not exist. 


5.1.8. set_initial_value (tsinitval^ 

Cerror set_initial_valuo(devclass, devnum, value) 
Cdevoff devclass; /* device type */ 

Cint devnum; /* device number */ 

Clnrep *value; /* device value */ 


set_initial_value sets the current measure of the specified device. This function resets the 
position of the track, if the track is appropriate and activated. set_initial_value also 
resets the request register. 


ERRORS: 


4 

ENOTVSAC 

CGI not in proper state: CGI shall be in state VSAC. 

80 

EINDNOEX 

Input device does not exist. 

81 

EINDINIT 

Input device not initialized. 

95 

EBADDATA 

Contents of input data record are invalid. 

96 

ESTRSIZE 

Length of initial string is greater than the implementation defined max- 


imum. 


5.1.9. set_valuator_range (tsvalrange^ 

Cerror set_valuator_range(devnum. min, max) 
Cint devnum; /* device number */ 

Cfloat min,max; /* limits of valuator */ 
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set_valuator_range specifies the limits of the valuator. Device coordinates are mapped into 
the valuator range. All valuator events which are on the event queue are not rescaled. You 
must dequeue these events either with the selectivo_f lush_of_event_queue function or 
flush_event_queue. 

ERRORS: 

4 ENOTVSAC CGI not in proper state: CGI shall be in state VSAC. 

80 EINDNOEX Input device does not exist. 

81 EINDINIT Input device not initialized. 

5.2. Tracking 

Tracking functions determine how the measure of an input device is displayed on the view sur¬ 
face. Each class of devices has its own set of possible tracks (given in Table 5-4). Although 
SunCGI allows certain classes of devices to track simultaneously, all types of input devices are 
not allowed to track at once. Tracking is not provided in the NOJJVENTS state unless the track 
type is PRINTERS_FIST. 


Table 5-5: Available Track Types 


Trigger 

Number 

Track Type 

IC.CHOICE 

1. 

PRINTERS_FIST 

IC_LOCATOR 

1. 

PRINTERS_FIST 

IC_STRING 

1. 

PRINTERS_FIST 


2. 

STRING.TRACK 

ICJSTROKE 

1. 

PRINTERS_FIST 


2. 

SOLIDJilNE 


3. 

XLXINE 


4. 

YJLINE 


5. 

RUBBER_BAND_BOX 

IC.VALUATOR 

1. 

PRINTERSJFIST 


2. 

STRING.TRACK 


5.2.1. track_on (Ctrackon^ 
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Cerror track_on(devclass, devnum, tracktype, trackreglon, value) 

Cdevoff devclass; /* device type */ 

Cint devnum; /* device number */ 

Cint tracktype; /* track nximber */ 

Ccoorpair ‘trackreglon /* window where track Is enabled */ 

Cinrep ‘value; /‘ device value ‘/ 

track_on initiates track (or echo) for a specific device. The tracktype argument specifies the 
type of track to be used. See table 5-5. The trackregion argument specifies a rectangular subre¬ 
gion of the view surface (in VDC Space) where tracking is active. The returned argument value 
reports the device measure at the time trackman is called. The track is initially displayed on the 
first view surface opened. 

The zypt element of value must be set to initially position the cursor. The reference point for 
IC_STR0KE echos 2 through 5 is the first point in the stroke array. The reference point for 
STRING_TRACK echo is the append_tex-t: concatenation point, and can be changed by calling 
text or append_text. The trackregion argument is not used and the device tracks in all 
areas of the view surface. 


ERRORS: 


4 

ENOTVSAC 

CGI not in proper state: CGI shall be in state VSAC. 

88 

EINECHON 

Track already on. 

91 

EINETNSU 

Track type not supported. 

95 

EBADDATA 

Contents of input data record are invalid. 

96 

ESTRSIZE 

Length of initial string is greater than the implementation defined max- 


imum. 


5 .£. 2 . track_off (ttrackoff^ 

Cerror track_off(devclass, devnum, tracktype, action) 

Cdevoff devclass; /‘ device type ‘/ 

Cint devnum; /‘ device number ‘/ 

Cint tracktype; 

Cint action; 

The function track^off terminates tracking for the specified input device. However, the printer’s 
fist track always remains. For this reason, the tracktype and the action arguments are always 
ignored. 

ERRORS: 

4 ENOTVSAC CGI not in proper state: CGI shall be in state VSAC. 

80 EINDNOEX Input device does not exist. 

81 EINDINIT Input device not initialized. 
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5.3. Event Functions 

Event functions allow the application program to set and obtain the current measure of input 
devices and triggers. No device-specific input routines exist in SunCGI. Therefore, each of the 
following functions requires explicit identification of an input device. There are two input 
buffers: the event queue and the request register. The event queue is a FIFO (First In, First Out) 
buffer containing input events which are not generated by the request functions. The request 
register is a one-element per device buffer which contains the measure caused by the last input 
event, if the device has been put in request^event mode. 

5.5.1. sainple_input CCsampiripj 

Cerror saiBple_input (devclass, devnum, valid, saniple) 

Cdevoff devclass; /* device type */ 

Cint devnum; /* device number */ 

Clogical ‘valid; /* device status */ 

Cinrep ‘sanple; /* device value */ 

sample_input reports the current measure of the specified input device in the returned argu¬ 
ment sample. The returned argument valid reports whether the device is initialized and 
prepared to receive an input. The current measure of the device may be set by a queued event, 
a requested event, or a device initialization depending on the state of the input device and the 
most recent trigger activation( 5 ). See the chapter introduction for an explanation of the relation¬ 
ship between the measure of an input device and the state of an input device. 

ERRORS: 

4 ENOTVSAC CGI not in proper state: CGI shall be in state VSAC. 

80 EINDNOEX Input device does not exist. 

81 EINDINIT Input device not initialized. 

5.5.2. initiate_request (Cinitreq^ 

Cerror initiate_request(devclass, devnum) 

Cdevoff devclass; /* device type */ 

Cint devnum; /* device number */ 

initiate_request sets up a device so that the measure resulting from the next trigger 
activation will be placed in the request register, initiate.request puts the device in the 
REQUEST_EVENT state. The value caused by the trigger activation can be obtained by the 
get_last_requested_inpu‘t function. 

ERRORS: 

4 ENOTVSAC CGI not in proper state: CGI shall be in state VSAC. 

80 EINDNOEX Input device does not exist. 

81 EINDINIT Input device not initialized. 
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85 EINNTASD No triggers associated with device. 


5.S.3. request_input (treqinp^ 

Cerror request_input(dovclass, devnum, timeout, valid, sample, trigger) 
Cdevoff devclass; /* device type */ 

Cint devnum; /* device number */ 

Cint timeout; /* amount of time to wait for input */ 

Cawresult ‘valid; /* device status */ 

Cinrep ‘sanple; /* device value ‘/ 

Cint ‘trigger /‘ trigger number ‘/ 

request_input awaits activation of a trigger associated with a_ specific device, for timeout 
microseconds. requeat_mput puts the input device in the RESPOND_EJVENT state. If a trigger is 
activated within this period, the activating trigger and the device measure are returned in the 
trigger and sample arguments respectively. If the trigger is not activated within this period, the 
current device measure is returned in the sample argument, trigger is set to zero. 

Cawresult is defined as an enumerated type as follows: 

typedef enum { 

VALID_DATA, 

TIMED_OUT, 

DISABLED, 

WRONG_STATE. 

NOT_SUPPORTED 
)■ Cawresult; 

valid is set to VALID_DATA if a trigger is activated within the specified timeout period and 
TIMED_OUT otherwise. If the device is not in the state RESPOND_EVENT, valid is set to DISABLED. 
If the device is not a legal device, valid is set to NOTJSUPPORTED. valid is set to WRONGJSTATE 
if SunCGI is not in state VSAC. 


ERRORS: 


4 

ENOTVSAC 

CGI not in proper state: CGI shall be in state VSAC. 

80 

EINDNOEX 

Input device does not exist. 

81 

EINDINIT 

Input device not initialized. 

94 

EINEVNEN 

Events not enabled. 

99 

EINNTRSE 

Input device not in state RESPOND EVENTS. 


5.3.4’ get_last_requested_input ^Cgetlastreqinp^ 

Cerror get_last_requested_input(devclass, devnum, valid, sasple) 

Cdevoff ‘devclass; /* device class and ntimber ‘/ 

Cint ‘devnum; 

Cloglcal ‘valid; /‘ device status ‘/ 

Cinrep ‘sasple; /‘ device value ‘/ 

get_last_requested_input returns the contents of the request register. The returned 
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argument valid reports if the device exists and is initialized. The returned argument sample 
reports the latest event in the request register. If no event is in the request register, the initial 
device value is reported. 

ERRORS: 

4 ENOTVSAC CGI not in proper state: CGI shall be in state VSAC. 

80 EINDNOEX Input device does not exist. 

81 EINDINIT Input device not initialized. 

5.S.5. enable_events ^Cenevents^ 

Cerror enable_events(devclass, devnxun) 

Cdevoff devclass; /* device type */ 

Cint devnum; /* device number */ 

Calling enable_event8 allows the specified device to put events on the event queue. enable_events 
puts the input device in the QUEUE_EVENT state. An error is generated if the device specified by 
devclass, devnum does not exist or is not initialized. 


ERRORS: 


4 

ENOTVSAC 

CGI not in proper state: CGI shall be in state VSAC. 

80 

EINDNOEX 

Input device does not exist. 

81 

EINDINIT 

Input device not initialized. 

93 

EIAEVNEN 

Events already enabled. 


5.S.6. disable_events ^Cdaeventsj 

Cerror disable_events(devclass, devnum) 

Cdevoff devclass; /* device type */ 

Cint devnum; /* device number */ 

disable_events prevents the specified device from putting events on the event queue or mak¬ 
ing new associations with triggers. disable_events puts the input device in the NO_EVENT 
state. However, existing entries on the event queue are not removed and existing associations 
remain, devclass, devnum must refer to an existing or initialized device or an error is produced. 


ERRORS: 


4 

ENOTVSAC 

CGI not in proper state: CGI shall be in state VSAC. 

80 

EINDNOEX 

Input device does not exist. 

81 

EINDINIT 

Input device not initialized. 

94 

EINEVNEN 

Events not enabled. 


5-12 


Revision A of 15 May 1985 








SunCGI Reference Manual 


Input 


5.S.7, await_event ^Cawaitevj 


Cerror await_event(timeout, valid, devclass, devnum, 

measure, messaga_link, replost, time_staiiy, qstat, overflow) 

Cint timeout; /* amount of time to wait for input */ 

Cawresult *valid; /* status */ 

Cdevoff *devclass; /* device type */ 

Cint *devn\im; /* device number */ 

Cinrep *measure; /* device value */ 

Cmesstype *message_link; /* type of message */ 

Cint *replost; /* reports lost */ 

Cint *time_stanp; /* time_staicp */ 

Cqtype *qstat; /* queue status */ 

Ceqflow ‘overflow; /* event queue */ 

await_event processes the event at the head of the event queue. If the event queue is EMPTY, 
then await_event waits for timeout microseconds for a trigger to be activated, valid is set to 
VALID_DATA if a trigger is activated within the specified timeout period and TIMED.OUT other¬ 
wise. valid is set to WRONG_STATE if SunCGI is not in state VSAC. 

If either the event queue is not empty or a trigger is activated, the class, the number, and the 
value of the device generating the event are reported in the returned arguments devclaas, dev¬ 
num, and measure. If timeout is less than 0, SunCGI waits until a trigger is activated. If two 
events on the event queue have the same trigger but different values, the argument, message^link 
is assigned to SIMULTANEOUS_EVENT_FOLLOWS; otherwise the argument messagejlink is set to 
SINGLE_EVENT. 

The replost and time^stamp arguments should be ignored and are always zero. The returned 
argument qstat reports the queue status after the event is removed from the head of the event 
queue. 


typedef enum ■{ 

NOT_VALID, EMPTY. NON_EMPTY, ALMOST_FULL, FULL 
} Cqtype; 

Qstat is set to EMPTY if the event queue has no pending events. Qstat is set to NON-EMPTY if 
the event queue has events pending, but is not FULL or ALMOST_FULL. Qstat is set to 
ALMOST_FULL if there is room for only one more event on the event queue. Qstat is set to FULL 
if there is no room for more events on the event queue. The argument overflow can assume one 
of two values: NO_OFLO, or OFLO. 

ERRORS: 

4 ENOTVSAC CGI not in proper state: CGI shall be in state VSAC. 

97 EINQOVFL Input queue has overflowed. 

5.4. Status Inquiries 

The current state of the input devices, triggers, and the event queue can be obtained by using 
the functions discussed in this section. 
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5 . 4 J. inquire_lid_state_list /Gqlldstatelisj 

Cerror inquire_lid_state_llst(devclass, devnum, valid, list) 

Cdevoff devclass; 

Cint devnum; /* device typo, device number */ 

Clogical ‘valid; /* device supported at all */ 

Cstatelist ‘list; /‘ table of descriptors ‘/ 

inquire_lid_state_list reports the status of a specific mput_ device specified by devciast 
and devnum. The argument valid reports whether the device is supported at all. The list argu¬ 
ment reports the track, associations, state, and measure of the device in the appropriate ele¬ 
ments of list. When checking the elements of list, first check the state element — if state is 
RELEIASE, the other elements of list are undefined. 

typedef struct ■{ 

Clidstato state; 

Cpromstate pronpt; 

Cackstate acknowledgement; 

Cinrep ‘current; 

Cint n; 

Cint ‘triggers; 

Cechotypo echotyp; 

Cechostate echosta; 

Cint echodat; 

)• Cstatelist; 

ERRORS: 

4 ENOTVSAC CGI not in proper state; CGI shall be in state VSAC. 

80 EINDNOEX Input device does not exist. 

5.4-2. inquire_licl_state /GqlldstateJ 

Cerror inquire_lid_state(devclass, devnum, valid, state) 

Cdevoff devclass; 

Cint devnum; /‘ device typo, device number ‘/ 

Clogical ‘valid; /‘ device supported at all ‘/ 

Clldstate ‘state; /‘ table of descriptors ‘/ 

inquire_lid_state reports the status of a specific input device specified by devclass and dev¬ 
num. The argument valid reports whether the device is supported at all. The state argument 
(of type Clidstate) reports the current state of the specified input device. 

typedef enum { 

RELEASE, NO_EVENTS, REQUEST_EVENT, RESPONDJEVENT, QUEUE_EVENT 
} Clidstate; 

ERRORS: 

4 ENOTVSAC CGI not in proper state: CGI shall be in state VSAC. 
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80 EINDNOEX Input device does not exist. 

5.4-3. inquire_trigger_state ^Cqtrigstate^ 


Cerror inquire_trigger_state(trigger, valid, list) 

Cint trigger /* trigger number */ 

Clogical ‘valid; /* trigger state */ 

Ctrigstate ‘list; /* trigger description table ‘/ 

inquire_trigger_state describes the binding between a trigger and an input device. If the 
state element of the returned argument list is INACTIVE, no associations have been made with the 
trigger. An error is generated if the trigger does not exist. 

typedef struct { 

Cactstate state; /* state */ 

Cassoclid ‘assoc; /* list of associations */ 
y ctrigstate; 

ERRORS: 

4 ENOTVSAC CGI not in proper state: CGI shall be in state VSAC. 

86 EINTRNEX Trigger does not exist. 


5 . 4 . 4 - inquire_event;_queue_st:ate ^Cqevquestatej 

Cerror inquire_event_queue_stato(qstat, qflow) 

Cqtype ‘ qstat; /* queue state */ 

Ceqflow • qflow; /* overflow Indicator */ 

inquire_event_queue_state reports the status of the event queue. Qstat indicates whether 
any events are pending. The argument qflow reports if the event queue is overflowing. 

typedef enum •( 

NOT_VALID, EMPTY, NON_EMPTY, ALMOST_FULL, FULL 
> Cqtype; 

typedef enuim { 

NO_OFLO, OFLO 
)■ Ceqflow; 

ERRORS: 

4 ENOTVSAC CGI not in proper state: CGI shall be in state VSAC. 
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Differences between SunCore and SunCGI 


This appendix provides an introduction to SunCGI for programmers who have programming 
experience with SunCore or graphics packages based on the ACM Core Graphics Specification. 
The three major differences between SunCore and SunCGI are in the areas of output primi¬ 
tives, segmentation, and input. While SunCore is generally a ‘higher-level’ package, SunCGI 
has capabilities which are not available in SunCore. 


A.l. Output Primitives 

The major differences in drawing objects to the screen between SunCore and SunCGI are that 

1. SunCGI does not support three-dimensional primitives, and 

2. SunCGI does not have floating-point world coordinates or image transforms, and, 

3. SunCGI does not support the concept of current position, and 

4. SunCGI does not support textured color lookup table for black-and-white devices. 

However, SunCGI provides a wider variety of geometrical and raster primitives, and more con¬ 
trol over the drawing of text. These differences are summarized in Table A-1. 


Table A-1: Difference in Output Primitives 


Feature 

SunCore 

SunCGI 

Three-Dimensional Output Primitives 

YES 

NO 

Current Position 

YES 

NO 

Textured Color Lookup Tables 

YES 

NO 

Polygons with Invisible Edges 

NO 

YES 

Circles and Ellipses 

NO 

YES 

Cell Arrays 

NO 

YES 

Character Clipping 

NO 

YES 
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A.Ll. Output Aspects of SunCore not Supported by SunCGI 

SunCGI does not support three-dimensional output primitives, current position, or textured 
color lookup tables for black-and-white devices. Since three-dimensional output primitives are 
not supported, no shading or lighting functions are provided either. Furthermore, no rotation or 
translation functions are provided. Therefore, if you want to rotate a geometrical output primi¬ 
tive, these operations must be done by your application program. 

Since SunCGI does not maintain the current position of the output ‘cursor’, relative drawing 
functions such as polygon^reLS are not supported. However, the application programmer can 
implement this function by specifying all coordinates as a base register plus a constant. The base 
register can be used by the application program to maintain the value of the current position. 

For black-and-white devices, SunCore interprets the entries in the color lookup table with 
indices greater than one as patterns. SunCGI interprets all color lookup table entries greater 
than zero as black. Patterns in SunCGI are explicitly specified in the pattern table and invoked 
by using the PATTERN or HATCH interior styles. In addition, while patterns in SunCore are all 
four-by-four matrices, patterns in SunCGI have variable dimensions. 


A. 1.2. Output Features of SunCGI not Available in SunCore 

SunCGI offers geometrical and raster primitives not available in SunCore, as well as increased 
control over the drawing of text. SunCGI provides circles and ellipses. SunCGI also supports 
the cell array which is a raster array whose element size is a function of the screen size. 
SunCGI clips characters in parts if the text precision is set to STROKE. 


A.2. Segmentation 

SunCGI does not support segmentation. This effect influences the effect of attribute calls. In 
SunCore, some attributes (for example, highlighting) apply to entire segments. Since no con¬ 
cept of segmentation exists in SunCGI, these attributes are not offered. Furthermore, SunCGI 
does not allow the saving or restoring of segments to the screen, so screen repainting functions 
must be completely defined by the application program, unless the view surface is initialized as a 
retained view surface and is not resized. 


A.3. Differences in Input Functions between SunCore and SunCGI 

SunCore provides device-specific functions for setting input device parameters and reading 
input from them. SunCGI provides no device dependent calls. SunCGI has three methods for 
obtaining the measure of input devices 

1. by first activation (REQUEST EVENT), 

2. by most recent activation (RESPOND EIVENT), or 

3. by mediating input requests through the event queue (QUEUE EVENT). 

Furthermore, SunCGI allows the explicit binding of triggers (physical input devices) to logical 
input devices. 
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Unsupported Aspects of CGI 


SunCGI does not support certain optional aspects of the proposed draft ANSI CGI standard. 
Most notably SunCGI does not support the full constellation of negotiation functions or track¬ 
ing. SunCGI does not allow the resetting of coordinate type, coordinate precision, or color 
specification mode because to do so would greatly reduce the speed of application programs writ¬ 
ten in SunCGI. Furthermore, SunCGI does not support echoing functions for input, but pro¬ 
vides the tracking functions instead. 

Unsupported Control Functions 
vdc_typo 

vdc_preclsion_for_integerjJOints 

vdc_precision_for_real_points 

integer_precislon 

real_precislon 

index_precislon 

CO lor_se lect ion_jnode 

color_precision 

CO1or_index_preclslon 

viewport_speci f icatlon_jnode 

make^ 1 ct ur e_curr ent 

Unsupported Input Functions 

set_pr on^ t_st ate 

set_acknowlodgement_stat 0 

echo_on 

echo_off 

echo_updato 

The following SunCGI functions are nonstandard (that is, are not in the standards document) 
and are included to make CGI easier to use. In addition, SunCGI has non-standard view surface 
arguments for certain control functions. 

Non Standard Control Functions 

open_cgi 

opGn_vws 

activato_ws 

deact1vatG_vws 

close_vws 

close_cgi 

Non Standard Attribute Functions 
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de flne_bundle_index 

line_ends'tyle 

fixed_font 

set_global_drawing_mode 



o 
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Type Definitions 


This appendix lists the types used by SunCGI functions. The definition of these types can be 
found in <cgitypes .h>. These definitions are listed here in alphabetical order to make the 
manual easier to read. 

typedef enum { 

ACK_ON, ACK_OFF 
} Cackstate; 



typedef enum ■( 

ACTIVE, INACTIVE 
). Cactstate; 

typedef enum -( 

CLEAR, NO_OP, RETAIN 
} Cacttype; 

typedef enum { 

INDIVIDUAL, BUNDLED 
} Casptype; 


typedef struct { 
Cint n; 
Cdevoff * class; 
Cint *assoc; 

} Cassoclid; 


typedef enum { 

CALID_DATA, 
TIMED_OUT, 
DISABLED, 
WRONG_STATE, 
NOT_SUPPORTED 
} Cawresult; 
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typedef eniim { 

BITTRUE, BITNOT 
}■ Cbltmapt:ype; 

typed© f enum •{ 

TRANSPARENT, OPAQUE 
} Cbmode; 

typedef struct •{ 

Clintypo lino_type; 

Cfloat llno_width; 

Clnt line_color; 

Cmartype marker_type; 

Cfloat marker_sizo; 

Cint marker_color; 

Cintortype interior_stylo; 

Cint hatch_index; 

Cint pattern_ind©x; 

Cint fill_color; 

Clintype perimot©r_typo; 

Cfloat perimetor_width; 

Cint perimet©r_color; 

Cint t©xt_font; 

Cprectype text_pr©cision; 

Cfloat character_expanslon; 

Cfloat character_spacing; 

Cint text_color; 

} Cbunatt; 

typedef struct { 

unsigned char *ra; 
unsigned char *ga; 
unsigned char *ba; 

Cint n; 

} Ccentry; 

typedef enum •{ 

OPEN, CLOSE 
} Ccflag; 
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typedef struct { 

Cint numloc; 

Cint nuicval; 

Cint numstrk; 

Cint numchoice; 

Cint numstr; 

Cint numtrig; 

Csuptype event_queue; 

Csuptype asynch; 

Csuptype coord_inap; 

Csuptype echo; 

Csuptype tracking; 

Csuptype pronpt; 

Csuptype acknowledgement; 
Csuptype trigger_manipulation; 
} Ccgidesctab; 


typedef enum {_ 
YES, NO 
)• Cchangetype; 


typedef char Cchar; 



typedef enum ■( 

CLIP, 

NOCLIP, 

CLIP_RECTANGLE 

} Cclip; 


typedef enum ■{ 
CHORD, PIE 
}■ Cclosetype; 


typedef enum •{ 

REPLACE, AND. OR, NOT, XOR 
)• Ccombtypo; 


typedef struct ■{ 
Cint x; 

Cint y; 

} Ccoor; 

typedef struct •( 
Ccoor *ptlist; 
Cint n; 

} Ccoorlist; 
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typedef struct { 
Ccoor *upper; 
Ccoor ‘lower; 
) Ccoorpair; 


typede f enum { 

IC_LOCATOR, 
IC_STROKE, 
IC_VALUATOR, 
IC_CHOICE, 
IC_STRING, 
IC_PICK 
J Cdevoff; 



typedef enum { 

E_TRACK. 

E_ECHO. 

E_TRACK_OR_ECHO, 
E_TRACK_AND_ECHO 
J Cechoav; 


typedef struct { 

Cinrep * echos; 

Cint n; 

} Cechodatalst; 

typedef enum { 

ECHO_OFF, ECHO_ON, TRACK_ON 
} Cechostate; 



typedef struct { 

Cechostate * echos; 

Cint n; 

)• Cechostatelst; 

typedef enum { 

PRINTERS_FIST. NO_ECHO, HIGHLIGHT, RUBBBR_BAND_BOX, 
DOTTED_LINE, S0L1D_LINE, STRING_ECHO, XLINE, YLINE 
} Cechotype; 


typedef struct { 

Cint n; 

Cechoav * elements; 
Cechotype * echos; 

} Cechotype1st; 

typedef enum ■{ 

NATURAL, POINT, BEST_FIT 
} Cendstyle; 
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typedef enum { 

NO_OFLO, OFLO 
} Ceqflow; 

typedef Cint Cerror; 

typedef enum •( 

INTERRUPT. NO_ACTION. POLL 
)• Cerrtype; 

typedef envun ■{ 

CLIP_RECT. VIEWPORT, VIEWSURFACE 
} Cexttype; 


typedef struct •£ 

Cintertypo stylo; 

Cflag visible; 

Cint color; 

Cint hatch_index; 

Cint pattern_indox; 

Cint index; 

Clintype pstyle; 

Cfloat pwidth; 

Cint pcolor; 

> Cfillatt; 


typedef enum { 
OFF. ON 
> Cflag; 


typedef struct { 
Cint n; 

Cint *num; 
Casptype *value; 
} Cflaglist; 


typedef float Cfloat; 

typedef enum { 

FREEZE. REMOVE 
} Cfreeze; 

typedef enum •( 

LFT, CNTER, RGHT. NRMAL, CNT 
} Chaligntype; 

typedef int Cint; 


Revision A of 15 May 1985 


C-5 






Type Definitions 


SunCGI Reference Manual 


typedef enum •{ 

NO_INPUT, ALWAYS_ON, SETTABLE, DEPENDS_ON_LID 
} Clnputability; 

typedef struct { 


Ccoor * 

xypt; 

/* 

LOCATOR ‘/ 

Ccoorlist *polnts; 

/* 

STROKE devices */ 

Cfloat 

val; 

/* 

VALUATOR device ‘/ 

Cint 

choice; 

/* 

CHOICE devices ‘/ 

Cchar 

‘string; 

/* 

STRING device ‘/ 

Cpick 

‘pick; 

/* 

PICK devices V 

}• C inrep; 




typedef enum •{ 



HOLLOW, 

SOLIDI, PATTERN, 

HATCH 



} Cintertype; 

typedef struct { 

Clogical san^le; 
Cchangetype change; 

Cint numassoc; 

Cint *trigassoc; 

Clogical pron^t; 

Clogical acknowledgement; 
Cechotype1st *echo; 

Cchar *classdep; 
Cstatelist state; 

} Cllddescript; 




typedef enum ■( 

RELEASE, NO_EVENTS, REQUEST_EVENT, RESPOND_EVENT, QUEUE_EVENT 
)• Clldstate; 


typedef struct ■{ 

Clintype style; 
Cfloat width; 

Cint color; 

Cint index; 

)■ Clinatt; 


typedef enum { 

SOLID, DOTTED, DASHED, DASHED_DOTTED, DASH_DOT_DOTTED, LONG_DASHED 
}• Cl intype; 


typedef en\UD ■( 

L_TRUE, L_FALSE 
} Clogical; 
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typedef struct { 

Cmartype type; 

Cfloat size; 

Cint color; 

Cint Index; 

} Cmarkatt; 

typedef enum { 

DOT, PLUS, ASTERISK, CIRCLE, X 
)• Cmartype; 

typedef enum { 

SIMULTANEOUS_EVENT_FOLLOWS, SINGLE_EVENT 
)■ Cmesstype; 


typedef enxun ■( 

RIGHT, LEFT, UP, DOWN 
} Cpathtype; 


typede f struct ■{ 

Cint cur_index; 

Cint row; 

Cint column; 

Cint *COlorlist; 

Ccoor *point; 

Cint dx; 

Cint dy; 

)■ Cpatternatt; 

typedef struct ■{ 

int segid; /* segment */ 

int pickid; /* pick id */ 

}■ Cpick; 

typedef struct pixrect Cpixrect; 

typedef enum { 

STRING, CHARACTER, STROKE 
)• Cprectype; 

typedef enum ■( 

PROMPT_ON, PROMPT_OFF 
} Cpromstate; 

typedef enum { 

NOT_VALID, EMPTY, NON_EMPTY, ALMOST_FULL, FULL 
} Cqtype; 
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typedef struct ■{ 

Clldstate state; 

Cpromstate prompt; 
Cackstate acknowledgeznent; 
Cinrep ‘current; 

Cint n; 

Cint ‘triggers; 
Cechotype echotyp; 
Cechostate echosta; 

Cint echodat; 

} Cstatelist; 


typedef enum •( 

ABSOLUTE, SCALED 
} Cspecmode; 


typedef enum ■{ 

NONE. REQUIRED_FUNCTIONS_ONLY, SOME_NON_REQUIRED_FUNCTIONS, 
ALL_NON_REQUIRED_FUNCTIONS 
} Csuptype; 

typedef struct { 

Cint fontset; 

Cint index; 

Cint current_font; 

Cproctype precision; 

Cfloat exp_factor; 

Cfloat space; 

Cint color; 

Cint height; 

Cfloat basex; 

Cfloat basey; 

Cfloat upx; 

Cfloat upy; 

Cpathtype path; 

Chaligntypo halign; 

Cvaligntype valign; 

Cfloat hcalind; 

Cfloat vcalind; 

} Ctextatt; 

typedef enum •( 

FINAL, NOT_FINAL 
)• Ctext final; 
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typedef struct ■{ 

Cchangetypo change; 
Cassoclid *numassoc; 
Cint maxassoc; 
Cpromstate proapt; 
Cackstate acknowledgement; 
Cchar *name; 

Cchar ‘description; 

} Ctrigdis; 

typedef struct •( 

Cactstate state; 

Cassoclid ‘assoc; 

} Ctrigstate; 


typedef enum { 

TOP, CAP, HALF, BASE, BOTTOM, NORMAL, CONT 
} Cvaligntype; 

typedef enum { 

INTEGER, REAL, BOTH 
)■ Cvdctype; 


typedef struct •{ 

Cchar screenname[DEVNAMESIZE] 
Cchar windowname[DEVNAMESIZE] 
Cint windowfd; 

Cint retained; 

Cint dd; 

Cint cmapsize; 

Cchar cmapname[DEVNAMESIZE]; 
Cint flags; 

Cchar “ptr; 

]■ Cvwsurf; 


/* physical screen */ 
/‘ window */ 

/* window file ‘/ 

/* retained flag */ 

/‘ device ‘/ 

/* color map size ‘/ 

/* color map name ‘/ 


/* new 


flag */ 
/* CGI 


tool descriptor ‘/ 
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Appendix D 


Error Messages 


This appendix lists the error messages in numerical and alphabetical order. Furthermore, the 
probable cause of each error is given in the sentences folio-wing the error. In addition to explain¬ 
ing the error message, an initial suggestion for corrective action is given. In the title for each 
group of errors, the range of error numbers is given in parentheses after the title. If your appli¬ 
cation program is not behaving as you want it to, but does not generate error messages, then the 
table at the end of this appendix which lists commonly encountered problems and frequent 
causes may be helpful. 


D.l* Successful Return (O) 

0 NO_ERROR (0) 

No error. 


D.2. State Errors (l-S) 


1 ENOTCGCL CGI not in proper state: CGI shall be in state CGCL. A call 
to open^cgi was attempted when cgi was already open. Elimination of the error 
can be accomplished by removing the offending call to open^cgi. 


2 ENOTCGOP CGI not in proper state: CGI shall be in state CGOP. Every 

function except open_cgi requires that CGI be open. If this error is received, 
make sure that your application program has called open_cgi, or that it has not 
recently called clote_cgi . 

3 ENOTVSOP CGI not in proper state: CGI shall be in state VSOP. The 

function which generated the error requires that at least one view surface be 
open. Corrective action would include either removing the most recent call to 
elose^vwt or by including a call to open^vwt. 


4 ENOTVSAC CGI not in proper state: CGI shall be in state VSAC. The 

function which generated the error requires that at least one view surface be 
active. Corrective action would include either removing the most recent call to 
deactivate^vwa or by including a call to activate^vwa. 


5 ENOTOPOP CGI not in proper state CGI shall be in state CGOP* VSOP* 
or VSAC. The function which generated the error requires that SunCGl is 
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at least initialized. If this error is received, make sure that your application 
program has called opetL.egt, or that it has not recently called elose^egi. 


D.3. Control Errors (10“16) 

10 EVSIDINV Specified view vurface naoie Is Invalid. The view surface name 

specified by the name argument has never been opened or if it has been 
opened, it has since been closed. Corrective action involves opening the view 
surface or changing the value of the name argument. 

11 ENOWSTYP Specified view surface type does not exist. The application 

program has specified a type of view surface which is not supported by 
SunCGI. Corrective action involves changing the type of view surface. 

12 EVSISOPN Specified view surface is open. An attempt was made to open a 

view surface which is already open. Corrective action involves removing one 
call to open_vw». 

13 EVSNOTOP Specified view surface not open. An attempt was made to close a 

view surface which is already closed. Corrective action involves removing one 
call to clo8e_vtV8. 

14 EVSISACT Specified view surface is active. An attempt was made to 

activate a view surface which is already activated. Corrective action involves 
removing one call to activate^vwa. 

15 EVSNTACT Specified view surface is not active. An attempt was made to 

deactivate a view surface which has already been deactivated. Corrective 
action involves removing one call to deactivate_vw8. 

16 EINQALTL Inquiry arguments are longer than list. A call to inquiry negotiar 

tion function with indices greater than the number of supported functions was 
made. The returned list is always empty. Corrective action may be facilitated 
by obtaining the size of the list by using the inquire_device^clas8 function. 


D.4. Coordinate Definition (20-24) 

20 EBADRCTD Rectangle definition is invalid. The application program has 

made a call to vdc_extent or device_vtewport with the coordinates of both 
corners equal in the x or y dimensions or both. Corrective action involves 
changing one of the arguments to the function which generated the error so 
that the values of the two arguments are different in both the x and y dimen¬ 
sions. 

21 EBDVIEWP Viewport is not within Device Coordinates. A call to 

device_viewport has been made which specifies a viewport which is larger than 
the view surface. Corrective action involves making the arguments to 
rfet;fcc_vicu^)orf less than the view surface size. The size of the view surface can 
be obtained by calling the inguire_phg8icaL.coordinate_8y$tem function. 
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22 ECLIPTOL Clipping rectangle le too large. The clipping rectangle would 

exceed the boundaries of VDC Space. Corrective action involves resetting the 
clipping rectangle to be within limits of VDC Space. 

23 ECLIPTOS Clipping rectangle Is too small. The clipping rectangle would 

define an area of screen space smaller than one pixel. The clipping rectangle 
remains unchanged. Since the occurrence of this error is partially a function of 
the size of the view surface, changing the size of the view surface may be a 
viable alternative to changing the size of the clipping rectangle. 

24 EVDCSDIL VDC space definition, is illegal. One or more of the arguments to 

the vdc_eztent function exceeds the acceptable limits (-32767 to 32767) or coor¬ 
dinates of the lower-left hand corner are greater than the coordinates of the 
upper-right hand corner. Corrective action involves changing the arguments to 
vdc_extent. 

D.5. Output Attributes (30-51) 

30 EBTBUNDL ASF is BUNDLED. Error 16 is generated when attempting to call an indivi¬ 

dual attribute function when the attributes are specified by entries in the attri¬ 
bute environment table. Calls to these functions have no effect on the current 
attributes. Corrective action includes resetting the attribute environment selec¬ 
tor to BUNDLED by using the set_attribute_environment_selector function. 

31 EBBDTBDI Bundle table index out of range. The entry in the bundle table 

exceeds the size of the table. The only corrective action is to change the value 
of the index argument. 

32 EBTUNDEF Bundle table index is undefined. The entry in the attribute 

environment table specified by the most recent call to 
set_attribute_€nvironment_table_index has not been defined by SunCGI or the 
application program. Corrective action includes defining the entry by calling 
define_attribute^environment^selector_index. 

33 EBADLINX Polyline index is invalid. The polyline bundle is not defined. Correc¬ 

tive action involves changing the index argument to polyline_bundle^index, or 
by defining the polyline bundle index. 

34 EBDWIDTH Width must be nonnegative. The width of a perimeter or line must be 

greater than or equal to zero. The current value of the perimeter width or line 
width remains unchanged. Changing the value of the width argument to a 
non-negative value will correct this error. 

35 ECINDXLZ Color index is less than sero. The value of the index argument to 

one of the attribute functions or the color entry in one of the bundles is nega¬ 
tive. Corrective action involves changing the value of the color. 

36 EBADCOLX Color index is invalid. The color index argument to one of the attri¬ 

bute functions or the color entry in one of the bundles is not defined in the 
colormap. Indices in the color lookup table must be between 0 and 255 for the 
Sun 8-bit per pixel frame buffer. Any color specification outside of this range is 
ignored. Corrective action involves changing the value of the color. 
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37 EBADMRKX Polymarker index is invalid. The polymarker bundle is not defined. 

Corrective action involves changing the index argument to 

polymarkerJbundle^index, or by defining the poljmiarker bundle index. 

38 EBADSIZE Slee maet. be nonnegablve. The size of a marker or line must be 

greater or equal to zero. The current value of the marker »ize remains 
unchanged. Changing the value of the size argument to a non-negative value 
will correct this error. 

39 EBADFABX Fill area index is invalid. The fill area bundle is not defined. 

Corrective action involves changing the index argument to 

filLarea_bundle^index, or by defining the polymarker bundle index. 

40 EPATARTL Pattern array too large . The pattern array must contain less than 257 

elements. The pattern is not entered into the pattern table. Corrective action 
involves designing a new pattern. 

41 EPATSZTS Pattern elxe too small. The pattern size must be at least two-by-two. 

The pattern is not entered into the pattern table. Corrective action could 
include designing a new pattern which includes several replications of the origi¬ 
nal pattern. 

42 ESTYLLEZ Style (pattern or hatch) index is less than xero. All indices 

in the pattern table must be positive. To fix this mistake, change the argument 
to the pattern_index or the hatch^index or the entries in the bundle table. 

43 ENOPATNX Pattern table index not defined. The argument to the katck^index 

or pattern_index function or the entry bundle table should be reset to 
correspond to a defined value. 

44 EPATITOL Pattern table index too large. The index argument to pattern_table 

exceeded the bounds of the pattern table. The pattern is not entered into the 
pattern table. Redefining the pattern index to be between one and ten will 
eliminate the error. 

45 EBADTXTX Text index is invalid. The text bundle is not defined. Corrective 

action involves changing the index argument to text_bundle_index, or by 
defining the text bundle index. 

46 EBDCHRIX Character index is undefined. All other character indices besides 1 

are undefined in SunCGI. The new character index is simply ignored. You are 
advised to ignore the character_index function entirely. 

47 ETXTFLIN Text font is invalid. The text fonts range from 1 to 6. All other 

integers do not correspond to actual fonts. Corrective action involves changing 
the argument to the text^ont_index function or resetting the font index in the 
text bundle 

48 ECEXFOOR Expansion factor is out of range. The character exparuion factor 

or the character tpace expansion factor would result in a character or a space 
which would exceed the bounds of the screen or would result in a character 
smaller than the limitations of the character drawing software. To eliminate 
this error, reset the offending value to within an acceptable range (0.1-2.0 are 
reasonable guidelines). 

49 ECHHTLEZ Character height is less than or equal to zero. The character 

height must be positive. Corrective action involves changing the argument to 
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the character height function or the element of the text bundle. 

50 ECHRUPVZ Length of character up vector or character base vector is 

sero. Both the character up vector and the character base vector must be 
nonzero. Corrective action involves changing the arguments to the 
character^orientation function or the element of the text bundles. 

51 ECOLRNGE RGB values must be between 0 and 255. The red, green, and blue 

values are only defined between 0 and 255. The call to color^table which pro¬ 
duced the error is ignored. Corrective action requires respecifying the values of 
the arguments to color^table. 

D.6. Output Primitives (60-70) 

60 ENMPTSTL Number of points is too large. The number of points exceeds 255. 

Change the n element of the ooorlist structure to a value less than or equal 
to 255. 

61 EPLMTWPT polylines must have at least two points. Change the » element 

of the coorlist structure to a value greater than 2 and add the correspond¬ 
ing points to the ptlist element. 

62 EPLMTHPT Polygons must have at least three points. Change the n element 

of the coorlist structure to a value greater than or equal to 3 and add the 
corresponding points to the ptlist element. 

63 EGPLISFL Global polygon list is full. The number of points on the global 

polygon list exceeds 256. The points which exceed 256 are ignored. This error 
can be corrected by inserting a call to polygon (which clears the global polygon 
list by displaying its contents) before the call to partiaLpolygon which caused 
the overflow. 

64 EARCPNCI Arc points do not li« on circle. The starting and ending points of 

either an open or close circular arc do not lie on the perimeter of the circle 
described by the arguments cl and rad. If this error occurs, the arc is not 
drawn. Corrective action may include determination of the endpoints with the 
application program (for example c2.x = rad*cos(start_angle);). 

65 EARCPNEL Arc points do not lie on ellipse . The starting and ending points of 

either an open or close elliptical arc do not lie on the perimeter of the ellipse 
described by the arguments cl,c2, and c3. If this error occurs, the arc is not 
drawn. Corrective action may include determination of the endpoints with the 
application program (see error 11). 

66 ECELLATS Cell array dimensions dx,dy are too small. The dimensions of 

the cell array are too small for a cell array element to be mapped onto one 
pixel of the view surface. The cell array is not drawn. This error depends on 
the physical size of the view surface as well as the limits of VDC Space. There¬ 
fore, corrective action might require changing the size of the view surface, VDC 
Space, or both. 

67 ECELLPOS Cell array dimensions must be positive. Negative cell array 

dimensions are not permitted. Corrective action requires changing the parame¬ 
ters to the cell array function. 
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69 EVALOVWS 

70 EPXNOTCR 

D.7. Input 

80 EINDNOEX 

81 EINDINIT 

82 EINDALIN 

83 EINASAEX 

84 EINAIIMP 

85 EINNTASD 

86 EINTRNEX 

87 EINNECHO 

88 EINECHON 


Value outelde of view surface. A coordinate of a pixel array is out¬ 
side the physical range of the view surface. The pixel array is not drawn. 
Change the arguments to the pixeLarray or bitblt^tource^array 

Plxreot. not created. One of the bitblt functions required a user-defined 
pixrect, and that pixrect had not been created. Corrective action involves 
creating a pixrect in your application program before calling the offending bitblt 
function. 

(80-97) 

Input device does not exist. The input device specification (specified 
by the devclast and devnum arguments of most input functions) does not exist. 
Corrective action involves resetting the device specification to a valid device. 

Input device not Initialized. A call to an input device function 
specified a device which was not initialized. Calls which generate this error 
have no effect. A call to initial{ze^input_device should be inserted before the 
call generating the error. 

Input device already initialized. An attempt to initialize a device 
which has previously been initialized. The parameters to the offending call to 
initialize_input_d€vice are ignored. Removing the offending call to 
initial{ze_input_deviee will correct this error. 

Association already exists. An attempt is being made to bind the 
input device to a trigger to which it has been previously bound. The status of 
the input device trigger are unchanged. This error is purely informational and 
no corrective action is required. 

Association is impossible. An attempt is being made to bind the 
input device to a trigger to which it cannot be bound. For example a 
IC_STRING device cannot be bound to a mouse button. To eliminate this 
error, change the arguments to the offending call of the aaaociate function. 

Association does not exist. An attempt to set-up call an input func¬ 
tion which specifies a device with no associated triggers was made. The 
offending call is ignored. Corrective action involves calling aaaociate before the 
offending call is issued. 

Trigger does not exist. An attempt was made to associate or inquire 
about a trigger which has a number less than one or greater than five. The 
offending call is ignored. To eliminate the error, change the trigger number. 

Input device does not echo. CHOICE devices do not support echo. 
Corrective action requires removing the call to echo^on from the application 
program. 

2cho already on. A call to echo_on has been made to a device whose echo¬ 
ing ability has already been activated. To stop generation of the error either 
remove the offending call or change the arguments to specify a device whose 
echo is currently off. 
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89 EINEINCP Echo ineonpatible with existing echos. Although SunCGI can 

support certain combinations of echos (such as ICJSTRING and 
IcjvOCATOR), not all combinations are supported. The easiest remedy is to 
remove the most recent call to echo_on from the application program. 

90 EINERVWS Eohoregion larger than view surface. Error 91 is generated when 

the rectangle defined by the echoregion argument exceeds the limits of VDC 
Space. To eliminate this error, change the values to the echoregion argument to 
be within the confines of VDC Space. 

91 EINETNSU Echo t 3 rpe not supported. All devices except the ICJSTROKE device 

only support one type of echo. Therefore, assigning a value to echotype other 
than zero or one will produce an error for any device except IC_STROKE. 
Corrective action involves changing the value of the echotype argument. 

92 EINENOTO Echo not on. The device echoing has not been turned on. Either remove 

the call to echo^off, turn the echo on, or change the device specification. 

93 EIAEVNEN Events already enabled. Events have already been enabled for the 

specified device. The solution is to remove the offending call to enable^evenU. 

94 EINEVNEN Events not enabled. Events have not been enabled for the specified dev¬ 

ice. The solution is to include a call to enable_events before a call to the 
await^event, sample^event, or requett^event function is made with the specified 
device as input parameter. 

95 EBADDATA Contents of input data record are invalid. The value argument 

of inittalize^lid function is out of range or is the wrong type. The solution is to 
change the contents value argument. 

96 ESTRSIZE Length of initial string is greater than the implementa¬ 

tion defined maximum. The initial string in the value argument is greater 
than 80 characters. Shorten the string. 

97 EINQOVFL Input queue has overflowed. The event queue can no longer record 

input events. Solutions include flushing the event queue or dequeueing events 
with the await_event, sample^event, or request^event function. 


D.8. Implementation Dependent (110) 

110 EMEMSPAC 

Space allocation has failed. A function which was supposed to work 
has failed. The only action which you can take is to eliminate other processes 
which may be using memory. If you have eliminated all other processes, and 
this error is still generated, please contact SUN Microsystems. 
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D.9. Possible Causes of Visual Errors 

c 

Table D-1: Possible Causes of Visual Errors 


Behavior 


Possible Cause 

Segmentation fault for open_vws 

a. 

devdd argument for open_vws is declared as 
a pointer (the address of devdd should be 
passed). 

No primitives displayed 

a. 

View surface not initialized. 


b. 

View surface not active. 


c. 

VDC to device coordinate mapping makes 
objects too small. 


d. 

Clipping rectangle is too small and clipping 
is ON. 


e. 

Perimeter visibility is set to OFF and interi¬ 
or style is set to HOLLOW. 


f. 

llne_color or filLcolor is set to background 
color. 

Primitives displayed on undesired view sur- 

a. 

Undesired view surfaces have not been deac- 

faces 


tivated. 

Segmentation fault for inquiry functions 

a. 

passing variable instead of address (&) of 
variable. 
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Table D-2: Primitive-Specific Errors 


Behavior 


Poteible Came 

Polylines or polymarkers aren’t displayed. 

a. 

Width or size is zero. 


b. 

Color is the same as background. 

Polygon borders aren’t displayed. 

a. 

Width is zero. 


b. 

Color is the same as background. 


c. 

Perimeter visibility is set to OFF. 

Circles aren’t displayed. 

a. 

Width or size is zero. 


b. 

Color is the same as background. 

Ellipses aren’t displayed. 

a. 

Width or size is zero. 


b. 

Color is the same as background. 

Text isn’t displayed. 

a. 

Width or size is zero. 


b. 

Color is the same as background. 


c. 

character height is too small. 


d. 

coordinates are outside the range of VDC 



Space or the clipping rectangle. 

Cell arrays aren’t displayed. 

a. 

Dx or dy arguments are too small. 


b. 

Color is the same as background. 

Cell arrays aren’t displayed on all active 

a. 

Mapping from cell size to view surface for 

view surfaces. 


smaller view surfaces is too small. 

Pixel arrays aren’t displayed. 

a. 

Location is outside of view surface or clip- 



ping rectangle. 


b. 

Color is the same as background. 

Bitblts aren’t displayed. 

a. 

Width or size is zero. 


b. 

Color is the same as background. 
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Table D-3: Attribute Errors 


Behavior 


Poaaible Cauae 

Attribute setting has no effect 

a. 

attribute ASF is set to BUNDLED. 

Text attributes have no effect 

a. 

text precision is set to CHARACTER. 


b. 

attribute ASF is set to BUNDLED. 

PATTERN fill is the same as HATCH 

a. 

pattern_index and hatch_index are identical 


b. 

pattern_size is too small 

PATTERN fill is different on different view 
surfaces. 

a. 

View surfaces are of different size. 


Table D-4: Input-specific Errors 


Behavior 


Poaaible Cauae 

Input device does not report 

a. 

device not initialized 

Input device does not echo 

a. 

echo not initialized 

Input device does not echo on whole view 

a. 

echo region not set to whole view surface. 

surface 
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Sample Program 


E.l. Martini Glass 

The following program draws a Martini glass. The figure drawn by this program is identical to 
figure drawn by the example given in the appendix of the SunCore manual. It is suggested that 
novice users attempt to write this program to familiarize themselves with SunCGI. 
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#ifndef lint 

static char sccsid[] = "®(#)glass.c 1.1 84/11/01 Copyr 1984 Sun Micro"; 
tendif 

#include <cgidefs.h> 

static Ccoorlist martinilist; 

static Ccoor glass_coords [10] = ■( 0,0 , 

- 10,0 

- 1,1 

- 1,20 , 

-15,35 
15,35 
1,20 , 

1.1 

10,0 

0,0 }; 

static Ccoor water_coords[2] = -(-12,33 , 

12,33 >; 


static Ccoor vpll = {-50,-10}; 
static Ccoor vpur = {50,80}; 



Cint name; 

main () 

{ 

Cvwsurf device; 



device.dd=PIXWINDD; 

open_cgi(); /* initialize CGI */ 

open_vws(&name,fidevice); /* open view surface */ 

vdc_extent{&vpll,&vpur); /* reset VDC space */ 

martinilist.ptlist=glass_coords; /* load polyline structure */ 
martinilist,n=10; 

polyline(&martinilist); /* draw glass */ 

martini1ist.pt1ist=water_coords; 

martinilist.n=2; /* draw waterline */ 

polyline(Smartinilist); 

sleep(10); /* display for 10 seconds */ 

close_vws(name); /* exit */ 

closo_cgi0; 

exit(O); 

} 
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CGI and Pixwins calls can be integrated in a single application program by using the Cgipw 
functions. However, the CGI standard does not provide for facilities for dealing with multiple 
overlapping windows. Many users would like to have the richness of CGI’s primitives combined 
with Pixwin’s ability to automatically take care of multiple (potentially overlapping) windows. 

If you decide to use CGI and Pixwins, you may not use the standard SunCGI calls. Instead 
you should use cgipw calls. For example, cgipw_polyline should be used instead of poly¬ 
line. Note that cgipw functions do not return error codes. 

Using SunCGI and Pixwins involves using the basic CGI primitives to include a CGI pixwin 
descriptor (type Ccgiwin) as the first argument. The routines implementing the CGI standard 
output and attribute functions for SunCGI functions take a structure containing a specific 
pixwin and attribute pointer as their first argument. However, the file <cgipw.h> should be 
included instead of <cgidefs.h> in the application program. The four functions 
open_pw_cgi, open_cgi_pw, close_cgi_pw, and closo_pw_cgi are necessary for 
managing the SunCGI/FixtPtn interface. 


F.l. open_pw_cgi 

Cerror open_pw_cgi() 

open_pw_cgi puts CGI in a known internal state by setting the attributes to the default values 
and setting the NDC to device coordinate mapping to 1:1. Therefore, unless the application pro¬ 
gram changes the mapping by explicitly calling CGI functions to reset the NDC to device coordi¬ 
nate mapping, all input and output primitives will use device coordinates. The origin of the dev¬ 
ice coordinates is in the upper left-hand corner instead of the lower left-hand corner. No stan¬ 
dard errors are specified. If open_pw_cgi returns a nonzero result, then the initialization 
failed. 


F.2. open_cgi_pw 
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Cerror open_cgi_pw (pw, desc, naste) 
plxwln *pw; /* pixwin */ 

Ccgiwin *desc; /* CGI pixwin descriptor */ 

Clnt name; 

open_cgi_pw makes the pixwin pointed to by pw known to the internals of CGI. Calls to all 
CGI primitives will affect this pixwin. Desc is a pointer to a CGI pixwin which is used as the first 
argument to cgipw function. However, CGI does not guarantee that a pixwin exists or is any 
other way properly initialized. Calls may also be made to any pixwin function (see example pro¬ 
gram). Multiple calls to open_cgi„pw will result in primitives being displayed on multiple 
view surfaces. Attributes are local and apply only to the specified pixwins which have been 
opened by using open_cgi_pw. 


F.3. close_cgi_pw 


Cerror close_cgi_pw(desc) 

Ccgiwin *desc; /* CGI pixwin descriptor */ 

close_cgi_pw takes the CGI pixwin descriptor desc as an argument and removes it from the 
list of pixwins that CGI writes to. The pixwin is not closed. 


F.4. close_pw_cgi 

Cerror close_pw_cgi() 

close_pw_cgi takes care of leaving CGI in an orderly state. This function should be called 
before exiting the application program. 


F.5. Using Cgipw 

After calling the two initialization functions (open_pw_cgi, open_cgi_pw) the user may call 
both pixwin and SunCGI primitives as specified in their respective manuals. Signals are not 
handled by SunCGI when it is used with pixwins. No error handling is done by cgipw func¬ 
tions — this makes cgipw more efficient but errors must be detected by the programmer. 
Therefore, the application program must Insure that the NDC to device coordinate mapping is 
changed when the window size is changed. The application program should not use both 
SunCGI and window system input functions, since both SunCGI and the window system share 
a common event queue. For example, events handled by a SunCGI function will not be han¬ 
dled by a window system called after the SunCGI call. 

The cgipw functions is given in the table below. If one of the functions that you want to use is 
not listed, then you should use the normal SunCGI function. Most of the functions listed below 
are output and attribute functions; however, the tracking functions are listed so that you can 
control which surfaces input devices echo on. The arguments of the Cgipw functions are the 
same as those of the SunCGI functions except that the first argument is always the desc argu¬ 
ment which is of type Ccgiwin. Desc is a pointer to pixwin descriptor obtained from the 
operi_cgi_pw function. 
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F.6. List of Cgipw Functions 


Table F-1: List of Cgipw Functions 


CGI Function Name 


Cgipw Function Name 


appond_text(flag, tstrlng) 


cglpw.append.text(desc, flag, tstrlng) 


c®ll_array(p, q, r, dx, dy, colorlnd) 

cglpw.cell.array(desc, p, q, r, dx, dy. colorlnd) 

character.asqjanslon.factor(sfac) 


cglpw.character.oxpansion.factor(desc, sfac) 


character.height(height) 


cglpw.character.height(desc, height) 


character_orlQntation(xup^ yup, xbaso^ 

cglpw.character.orlentation(desc, xup, yup, xbase. 

ybase) 


ybase) 


character.path(path) 


cglpw.character.path(desc, path) 


character_set_lndex(Index) 


cglpw.character.set.lndex(desc. Index) 


character.spaclng(spcratlo) 


cglpw.character.spacing(desc, spcratlo) 


circle (cl, rad) 


cglpw.clrcle(desc, cl, rad) 


circular_arc_3pt(cl, c2, c3) 


cglpw_clrcular.arc.3pt(desc, cl, c2, c3) 


clrcular_arc_3pt_close(cl, c2. 

c3. 

cglpw_clrcular_arc_3pt_closa(desc, cl, c2. 

c3. 

close) 


close) 


clrcular_arc_center(cl, c2x, c2y. 

c3x. 

cglpw.circular.arc.center(desc, cl, c2x, c2y. 

c3x. 

c3y, rad) 


c3y, rad) 


clrcular.arc.center.close(cl. 

c2x. 

cglpw.circular.arc.center.close(desc, cl. 

c2x. 

c2y, c3x, c3y, rad, close) 


c2y, c3x, c3y, rad, close) 


deflne.bundle.lndex(Index) 


cglpw.deflne.bundle_lndex(desc. Index) 


disjoint jjolyllne(polycoors) 


cglpw.dlsjolnt.polyllne(desc, polycoors) 


ellipse(cl, majx, mlny) 


cglpw.e11Ipse(desc, cl, majx, mlny) 


elllptlcal.arc(cl, sx, sy, ex. 

ey. 

cgipw.elllptlcal.arc(desc, cl, sx, sy, ex. 

ey. 

majx, mlny) 


majx, mlny) 


elliptlcal.arc.close(cl, sx, sy. 


cglpw.elliptlcal.arc.close(desc, cl, sx, sy. 

AX, 

ey, majx, mlny, close) 


ey, majx. mlny, close) 


f11l.areajbundle.lndox(Index) 


cgipw.f11l.areaJaund1e_index(desc, Index) 


flll.color(color) 


cglpw.flll.color(desc, color) 


flxed.font(index) 


cglpw.flxed.font(desc. Index) 


hatch.lndex(Index) 


cglpw_hatch.lndex(desc. Index); 


Inqulre.aspeet.source.flags() 


cglpw.lnqulre.aspect.source.flags(desc); 


Inqulre.drawlng.mode(visibility. 


cglpw_lnqulro_drawing,jnod« (desc^ visibility. 

source, destination, combination) 


source, destination, combination) 


inquire.f11l.area.attrlbutes() 


cglpw.lnqulre.f11l.area.attrlbutes(desc); 


Inqulre.llne.attrlbutes() 


cglpw.lnquire.line.attributes(desc); 


Inqulrejnarker.attributes () 


cglpw.lnqulre_marl<er_attrlbutos(desc); 


lnqulre.pattern.attrlbute8() 


cglpw_lnqulra_pattern_attrlbutes(desc); 


Inquirejslxel.array(p, m, n, colorlnd) 

cglpw.lnqulroj>lxel_array(desc, p, m, n, color 

Ind) 

Inqulre.text.attributes() 


cglpw.lnqulre.text.attrlbutes(desc); 
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CGI Function Name 

Cgipw Function Name 

lnqulre_t®xt_extent(tstrIng, nextchar, 
concat. Heft, uleft, urlght) 
lnterlor_style(lstyle, porlmvls) 
llno_color(Index) 
llnG_endstyle(ttyp) 
llne_type(ttyp) 

cglpw_in<iulro_text_extent(desc, tstring, nextchar, 
concat. Heft, uleft, uright) 
cglpw_lnterlor_style(desc, Istyle, perlmvls) 
cglpw_line_color(desc, index) 
cglpw_llne_endstyle(desc, ttyp) 
cglpw_llne_typo(desc, ttyp) 

llnG_wldth(index) 

line_wldth_speclflcatlon_modo(mode) 
inarker_color(Index) 
inarkGr_slze (index) 

inarkor_size_Bpecification_mode (node) 

cglpw_llnG_width(desc, index) 

cglpw_llne_width_speclfication_mode(desc, mode) 
cglpv_markar_color(desc, index) 
cgipv_marker_8lze(desc, index) 

cglpw_marker_slze_speclflcatlon_mode(desc, node) 

marker_type(ttyp) 
pattern_index(index) 
pattern_reference_polnt(open) 
pattern_slze(dx, dy) 
pattern_table(index, m, n, colorind) 

cglpw_marker_type(desc, ttyp) 
cgipw_pattern_lndex(desc, index ): 
cglpw_pattern_reference^olnt (desc, open) 
cglpv_pattern_slze(desc, dx, dy) 
cglpv_pattern_table(deBC, index, m, n, colorind) 

perimeter_color(index) 
per iiiieter_type (ttyp) 
perimeter_width(index) 

perimeter_width_specification_modo(mode) 

pixel_array(pcell, n, n, colorind) 

cgipw_perimeter_color(desc, index) 
cglpw_porlmoter_type (desc, ttyp) 
cgipw_porlmeter_wldth(desc. Index) 
cglpw_jporlmotor_wldth_spocificatlon_mode (desc, 
mode) 

cglpw_plxel_array(desc, pcell, m, n, colorind) 

polygon(polycoora) 

polyline(polycoors) 

poly1lne_bund1e_lndex(index) 

polymarker (polycoors) 

polymarker_bundle_Index(index) 

cgipw_polygon(desc, polycoors) 
cglpw_polyline(dosc, polycoors) 
cgipv_poly1ine_l>undle^index(desc, index) 
cglpw_j>olymarker (dose, polycoors) 
cglpw_polymarkor_l>undle_Index(desc, index) 

rectangle(Ire, ulc) 
set_aspect_source_flags(flags) 
text(cl, tstring) 

text_allgnment(hallgn, vallgn, 

hcallnd, vcallnd) 
text_l>tindle_index (index) 

cgipv_rectangle(desc. Ire, ulc) 
cglpw_set_aspoct_sourco_flags(desc, flags) 
cglpw_text(desc, cl, tstring) 

cglpw_taxt_allgnmont(desc, hallgn, vallgn, 

hcallnd, vcallnd) 

cglp^f_text_l>undlo_lndex(dosc, index) 

text_color(index) 
text_font_lndex(index) 
toxt_prGclslon(ttyp) 
track_off(devclass, devnum) 
track_on(devclaBS, tracktype, trackre- 
gion, value) 

cglpw_toxt_color(desc, index) 
cgipw_toxt_font_lndox(desc, Index) 
cglpw_toxt_procislon(dosc, ttyp) 
cglpw_track_off(desc, devclass, devnum) 
cglpw_track_on(do8c, devclass, tracktype, trackre- 
gion, value) 

vdT«L.text (cl, flag, tstring) 

cgipw vdoL-text(desc, cl, flag, tstring) 


o 
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F.7. Example Program 


#include < cgipw.h> 

#include <suntool/gfxsw.h> 

struct pixwin *mypw; 
struct gfxsubwindow ‘mine; 

main () 

Ccgiwin vpw; 

Ccoor bottom; 

Ccoor top; 
int name; 

int op; 

mine = gfxsw_init(0, O); 
gfxsw_getretained(mine); 
mypw = mine->gfx_pixwin; 

pw_writebackground(mypw, O, 0, mypw->pw_prretained->pr_size.x, 
mypw->pw^rretained->pr_size.y, PIX_CLR) ; 
open_pw_cgi () ; 

open_cgi_pw(mypw, &vpw, finame); 

op = PIX_C0L0R(1) I PIX_SRC; 

pw_write(mypw, O, O, lOO, 100, op, O, O, 0); 

bottom.X = 300; 

bottom.y = 100; 

top.x = 200; 

top.y = 0; 

cgipw_interior_style(&vpw, SOLIDI, ON); 
cgipw_rectangle(fivpw, &bottom, Stop); 
sleep(10); 
close_cgi_pw(name); 
close_pw_cgi(); 

} 
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Appendix G 



Using SunCGI with Fortran-77 Programs 



All functions provided in SunCGI may be called from FORTRAN-77 programs by linking them 
■with the /utr/lib/libcgi77,a library. This is done by using the f77 compiler with a command 
line such as: 

tutorial% £77 -o grab grab.f -lcgi77 —Icgl -launwlndow —Iplxrect —Im 

where grab.f is the FORTRAN source program. Note that /uar/lib/libcgt.a must be linked with 
the program (the — Icgi option), and /uar/lib/libcgi77.a must come before it (the — lcgi77 
option). 

Defined constants may be referenced in source programs by including cgidefs77 .h. In a FOR¬ 
TRAN program, this must be done via a source statement like: 

include 'cgidefs77.h' 

This include statement must be in each FORTRAN program unit which uses the defined constants, 
not just once in each source program file. 

In the Sun release of FORTRAN-77, names are restricted to sixteen characters in length and may 
not contain the underline character. For this reason, FORTRAN programs must use abbreviated 
names to call the corresponding SunCGI functions. The correspondence between the full 
SunCGI names and the FORTRAN names appears later in this appendix. In addition, FORTRAN- 
77 declarations for all SunCGI functions appear at the end of this appendix. 



G.l. Programming Tips 

• The abbreviated names of the SunCGI functions are less readable than the full length names 
because the underline character cannot be used in the FORTRAN names. However, since FOR¬ 
TRAN doesn’t distinguish between upper-case and lower-case letters in names, upper-case char¬ 
acters can be used to improve readability. There is an example of this later in this appendix. 

• Character strings passed from FORTRAN programs to SunCGI cannot be longer than 256 
characters. 

• FORTRAN passes all arguments by reference. Although some SunCGI functions receive argu¬ 
ments by value, the FORTRAN programmer need not worry about this. The interface routines 
in /utr/lib/libcgi77.a handle this situation correctly. When in doubt, look at the FORTRAN 
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declarations for SunCGI functions at the end of this appendix. 

• Some SunCGI structures contain both int’s and float’s. For instance, the argument to 
inquire_viewing_parameters contains both int’s and float’s. This can be handled in 
FORTRAN by declaring a real array and an integer array and making them share storage 
by using an equivalence statement. Following the call to the inquiry function, the real 
components can be accessed using the real array and the integer components can be 
accessed using the integer array. 

• Since FORTRAN does not distinguish between upper-case letters and lower-case letters in 
identifiers, any FORTRAN program unit which includes the cgidef»77.k header file cannot use 
the same spelling as any constant defined in that header file, regardless of case. 


G.2. Example Program 

This example is the FORTRAN equivalent of the very simple program for drawing a martini glass. 

Include *cgidefs77.h' 

integer vsurf(VWSURFSIZE) 

Integer name 

Integer glassdx(9), glassdy(9) 

data glassdx /—10,9,0,—14,30,—14.0,9,—10/ 

data glassdy /0,1,19,15,0,-15.-19,-1, 0/ 

integer waterdx(9), waterdy(9) 

data waterdx /—10, 9,0,—14,30,—14,0,9,—10/ 

data waterdy /0,1,19,15,0,—15,—19,—1, 0/ 

c initialize CCI 

call cfopencgi 
c open the view surface 

call cfopenvws(name, , PIXWINDD, , ,) 
c reset VDC space 

call cfvdcext(vpll, vpur) 
c drawr glass 

call cfpolyline(glassdx, glassdy, 10) 
c draw water surface 

call cfpolyline(waterdx, waterdy, 9) 
c display for 10 seconds 
call sleep(10) 
c close the view surface 

call cfclosevws(name) 
c close cgi and exit 

call cfclosecgi 
c 

end 
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G.3. Correspondence Between C Names and FORTRAN Names 


Correspondence Between C Names and FORTRAN Names 

Long Name 

FORTRAN Equivalent 

activate_vws 

append_text 

associate 

await_event 

bitb1t_pattern_array 

cfactvws 
cfaptext 
cfassoc 
cfavaltev 
cfbtblpatarr 

bitblt_patterned_source_array 
bitb1t_source_array 
cell_array 

character„expansion_factor 
character_height 

cfbtblpatsouarr 

cfbtblsouarr 

cfcellarr 

cfcharexpfac 

cfcharheight 

character_orientation 

character_path 

character_set_index 

charactei*_spacing 

circle 

c fcharorientation 
cfcharpath 
cfcharsetix 
c fcharspacing 
cfcirclo 

circu1ar_arc_3pt 
circu1ar_arc_3pt_close 
circular_arc_center 
circu1ar_arc_center_c1ose 
clear_control 

c fcircarcthree 

cfcircarcthreecl 
c fcircarccent 
cfcircarccentcl 

cfclrcont 

c1ear_view_sur face 
c1ip_indicator 
clip_rectangle 
close_cgi 
close_vws 

cfclrvws 

cfclipind 

cfcliprect 

cfclosecgi 

cfclosevws 

color_table 

deactivate_vws 

de finejbundle_index 

device_viewport 

disable_events 

cfcotable 

cfdeactvws 
cfdefbundix 
cfdevvpt 
cfdaevents 

disjoint_polyline 
dissociate 
echo_o f f 
echo_on 
echo_update 

cfdpolyline 
cfdissoc 
cfechooff 
cfechoon 
cfechoupd 

ellipse 

elliptical_arc 

cfellipse 

cfelliparc 
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Corretpondence Between C Names and FORTRAN Names 

Long Name FORTRAN Equivalent 

elliptical_arc_close 
en ab1e_events 
fill_area_bundle_index 

cfelliparccl 
c fenevents 

c f f1areabundix 

fill_color 

fix©d_font 

f1ush_event_queue 

get_ 1 ast_reciuested_input 

hard_reset 

cffIcolor 

cffixedfont 
c f flusheventqu 
c f get1astr©qinp 
cfhardrst 

hatch_index 
initializo_lid 
initiate_request 
inquire_aspect_source_flags 
inquire_bitb1t_a1ignments 

c fhatchix 
cfinitlid 
cfinitreq 
cfqasfs 
cfqbtblalign 

inquire_cell_array 
inc[uire_device_bitmap 
incjuir e_device_c lass 
inquire_device_identification 
inq[uire_drawing_mode 

cfqcellarr 

cfqdevbtmp 

cfqdevclass 

cfqdevid 

cfqdravmode 

inc[uire_event_queue 
inquire_ fi1l_ar©a_attributes 
inquire_input_capabilities 
inquire_1id_cap abl1ities 
incjuire_ 1 id_state_l ist 

cfqevque 
cfqflaroaatts 
cfqinpcaps 
cfqlidcaps 
cfqlidstate 

inquire_lid_state_list 
inquire_1ine_attributes 
inquire_marker_attributes 
inqpj(ire_output_c ap abi 1 it ies 
inquire_output_ function_set 

c fqlidstate1is 
cfqlnatts 
c fqmkatts 
cfqoutcap 
c fqout funset 

inquiro_pattern_attributes 

inquire_physical_coordinate_systein 

inquire_pixel_array 

inquire_text_attributes 

inquire_text_extent 

cfqpatatts 
cfqphyscsys 
cfqpixarr 
cfcftoxtatts 
c fqtextext 

inquire_trigger_capabilities 

inquir©_trigger_stato 

inc[uire_vdc_typo 

interior_style 

line_color 

cfcjtrigcaps 
c fqtrigstato 
cfqvdctype 
cfintstyle 
cfIncolor 

1ine_endstV1e 

cfInendstyle 
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Correspondence Between C Names and FORTRAN Names 


Long Name 

FORTRAN Equivalent 

line_type 

line_widt:h 

line_widt:h_speclfication_modo 

marker_color 

cfIntype 
cfInwidth 
cfInwidthspecmode 
cfmkcolor 

inarker_siz© 

inarker_sizo_specification_modo 

inarker_t:ypo 

open_cgi 

open_vws 

cfmksize 

c fmksizespecmode 
c fmktype 
cfopencgi 
cfopenvws 

partial^polygon 
pattern_index 
pat:tern_re f erenco_point: 
pat;t:ern_size 
pattern_table 

cfppolygon 

cfpatix 

cfpatrofpt 

cfpatsize 

cfpattable 

perinieter_color 

perimeter_typo 

perinieter_widt:h 

perimeter_width_specificat:ion_mode 

pixel_array 

cfperimcolor 
cfperimtype 
c fperimvidth 
c fperimvidthspecmode 
cfpixarr 

polygon 

polyline 

poly1ine_bundle_index 
polymarker 

polymarker_bundle_index 

cfpolygon 
cfpolyline 
cfpolylnbundix 
c fpolymarker 
c fpolymkbundix 

rectangle 

reloase_input_device 
request_input 
reset_to_defaults 
sample_input 

cfrectangle 
cfrelidev 
c freqinp 
cfrsttodefs 
cfsampinp 

selective_ f1ush_o f_event_queue 
set_aspect_source_ flags 
set_dofault_trigger_associations 
set_dr awing_mode 
set_error_warning_mask 

cfselectflusheventqu 
cfsaspsouflags 
c fsde fatrigassoc 
cfsdrawmode 

c fserrwarnmk 

set_global_drawing_mode 

set_initial_value 

set_up_sigwinch 

s©t_valuator_rango 

text 

cfsgldrawmode 

cfsinitval 

cfsupsig 

cfsvalrange 

cftext 
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Correspondence Between C Names and FORTRAN Names 

Long Name 

FORTRAN Equivalent 

text_a1ignmont 

cftextalign 

text_bundle_index 

c ftextbundix 

text_color 

cftextcolor 

text_font_index 

c ftext fontix 

text_precision 

cftextprec 

vdc_extent 

cfvdcext 

vdm_text 

c fvdmtext 



G.4. FORTRAN Interfaces to SunCGI 

Note: Although all SunCGI procedures are declared here as functions, each may also be called as 
a subroutine if the user does not want to check the returned value. 

integer function cfactvws(name) 
integer name 


integer function cfaptext(flag^ string, stringlen) 
integer flag 
character*(*) string 
integer stringlen 



integer function cfassoc(trigger, devclass, devnum) 
integer trigger 
integer devclass 
integer devnum 
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integer function cfawaitev(timeout, valid, devclass, devnum, 

1 X, y, xlist. ylist. n, val, choice, string, rtringlen, 

2 message_link, replost, time.stanqp, qstat, overflow) 


Integer 

timeout 

integer 

valid 

integer 

devclass 

integer 

devnum 

integer 

X. y 

integer 

xlist (*) 

integer 

ylist (*) 

integer 

n 

real 

val 

integer 

choice 

character 

* (*) string 

integer 

stringlen 

integer 

message^link 

integer 

replost 

integer 

time_starnp 

integer 

qstat 

integer 

overflow 


integer function cfbtblpatarr(pixpat, px, py, pixtarget. 


rx. 

ry, ox, oy. 

integer 

pixpat 

integer 

px. 

py 

integer 

pixtarget 

integer 

rx. 

ry 

Integer 

ox. 

oy 

integer 

dx. 

dy 


integer function cfbtblpatsouarr(pixpat, px, py, pixsource, 
1 sx, sy, pixtarget, rx. ry, ox, oy, dx, dy) 


integer 

pixpat 

integer 

px. py 

integer 

pixsource 

integer 

sx, sy 

integer 

pixtarget 

integer 

rx, ry 

integer 

ox, oy 

integer 

dx, dy 


integer function cfbtblsouarr(bitsource, xo, yo, xe, ye, bittarget, xt, yt) 
integer bitsource, bittarget 
integer xo, yo, xe, ye, xt, yt 


integer function cfcellarr(px, 
integer px, py 

integer qx, qy 

integer rx, ry 

integer dx, dy 

integer colorind(*) 


qx, rx, py, qy, ry, dx, dy, colorind) 
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integer function cfcharexpfac(efac) 
real efac 


integer function cfcharheight(height) 
integer height 


integer function cfcharorient(bx, by, dx, dy) 
real bx, by, dx, dy 

integer function cfoharpath(path) 
integer path 


integer function cfcharsetix(index) 
integer index 


integer function cfcharspacing(efac) 
real efac 


Integer function cfcircarccent(clx, cly, c2x, c2y, c3x, c3y, rad) 
integer clx, cly, c2x, c2y, c3x, c3y 
integer rad 


integer function cfcircarccentcl(clx, cly, c2x, c2y, c3x, c3y, rad, close) 
integer clx, cly, c2x. c2y, c3x, c3y 
integer rad 
integer close 


integer function cfcircarcthree(clx, cly, c2x, c2y, c3x, c3y) 
integer clx, cly, c2x, c2y, c3x, c3y 


integer function cfcircarcthreecl(clx, cly, c2x, c2y, c3x, c3y, close) 
integer clx, cly, c2x, c2y, c3x, c3y 
integer close 


integer function cfcircle(x, y, rad) 
integer x 
integer y 
integer rad 

integer function cfclipind(flag) 
integer flag 

integer function cfcliprect(xmin, xmax, ymin, ymax) 
integer xmin, xmax, ymin, ymax 


integer function cfclosecgi() 


G-8 


Revision A of 15 May 1985 



SunCGI Reference Manual 


Using SunCGI with Fortran-77 Programs 




integer function cfclrcont(soft, hard, intern, extent) 
integer so ft, hard 
integer intern 
integer extent 


integer function cfclrvws(name, defflag, color) 
integer name 
integer defflag 
integer color 

integer function cfcotable(istart, ra, ga, ba, n) 
integer istart 
integer ra(*), ga(*), ba(*) 
integer n 


integer function cfdaevents(devclass, devnum) 
integer devclass 
integer devnum 


integer function cfdeactvws(name) 
integer name 


integer function cfdewpt(name, xbot, ybot, xtop, ytop) 
integer name 

integer xbot, ybot, xtop, ytop 


integer function cfdissoc(trigger, devclass, devnum) 
integer trigger 
integer devclass 
integer devnum 


integer function cfdpolyline(xcoors, ycoors, n) 
integer xcoors 
integer ycoors 
integer n 


integer function cfechooff(devclass, devnum, echo) 
integer devclass 
integer devnum 
integer echo 
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integer function cfechoon(devclass, echotype, exlow^ eylow, 

1 exup, eyup, x, y, xlist. ylist, n, val, choice, string, strlnglen) 

Integer devclass 
integer echotype 
integer exlow 

integer eylow 
integer exup 
integer eyup 
integer x, y 
integer xlist(*) 
integer ylist(*) 

Integer n 
real val 

Integer choice 
character*(*) string 
integer strlnglen 



Integer function cfechoupd(echo, x, y, xlist, ylist, n, val, 
1 choice, string, strlnglen) 

integer echo 
integer x, y 
integer xlist(*) 

integer ylist(*) 
integer n 
real val 

integer choice 
character*(*) string 
integer strlnglen 



integer function cfelliparc(x, y , sx, sy, ex, oy, majx, miny) 
integer x, y 
integer sx, sy 

Integer ex, ey 

integer majx, miny 


integer function cfelliparccl(x, y , sx, sy, ex, ey, majx, miny, close) 
Integer x, y 
integer sx, sy 

Integer ex, ey 

integer maj x, miny 

integer close 


integer function cfellipsefx, y, majx, miny) 
integer x, y 
integer majx, miny 


integer function cfenevents(devclass, devnum) 
integer devclass 
Integer devnum 
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integer function cffixedfont(index) 
integer index 

integer function cfflareabundix(index) 
integer index 


integer function cfflcolor(color) 
integer color 


integer function cfflushevontqu() 


integer function cfgetlastreqinp(devclass, devnum, valid, 

1 X, y, xlist, ylist, n, val, choice, string, stringlen) 

integer devclass 
integer devnum 
integer valid 
integer x, y 
integer xlist(*) 
integer ylist(*) 
integer n 
real val 

integer choice 
character*(*) string 
integer stringlen 


integer function cfhardrst() 

integer function cfhatchix(index) 
integer index 


integer function cfinitlid(devclass, devnua, x, y, xlist, ylist, n, val, 
1 choice, string, stringlen) 


integer 

devclass 

integer 

devnum 

integer 

X, y 

Integer 

xlist (*) 

integer 

ylist (*) 

integer 

n 

real 

val 

Integer 

choice 

character 

*(*) string 

Integer 

stringlen 


Integer function cflnitreq(devclass, devnum) 
integer devclass 
integer devnum 
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integer function cfintstyle(istyle, perimvis) 
integer istyle 
integer perimvis 

integer function cflncolor(index) 
integer index 

integer function cfInendstyle(ttyp) 
integer ttyp 

integer function cflntypo(ttyp) 
integer ttyp 

integer function cflnwldth(index) 
real index 

integer function cflnwidthspecmode(mode) 
Integer mode 

integer function cfmkcolor(index) 
integer index 

integer function cfmksize(index) 
real index 

integer function cfmksizespecmode(mode) 
integer mode 

integer function cfmktype(ttyp) 

Integer ttyp 

integer function cfopencgi() 
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integer function cfopenvws(name, screenname, screenlen, 

1 vindowname, wlndowlen, wlndowfd, retained, dd, 

2 cmapslze, cmapname, cmaplen, flags, ptr, noargs) 
Integer name 

character*(*) screenname 
Integer screenlen 
character*(*) windownamo 
integer wlndowlen 
integer wlndowfd 
Integer retained 
Integer dd 
Integer cmapslze 
integer cmapname(* ) 

Integer cmaplen 
Integer flags 
character*(*) ptr 
Integer noargs 

Integer function cfpatlx(Index) 

Integer Index 

integer function cfpatrefpt(x, y) 
integer x, y 

Integer function cfpatslze(dx, dy) 
integer dx, dy 

integer function cfpattable(index, m, n, colorlnd) 
Integer index 
integer m, n 
integer colorlnd 

integer function cfperimcolor(index) 
integer index 

integer function cfperlmtype(ttyp) 
integer ttyp 

integer function cfperimwidth(index) 
real index 

integer function cfpixarr(px, py, m, n, colorlnd) 
integer px, py 
integer m, n 
integer colorlnd(*) 
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integer function cfpolygon(xcoors, ycoors, n) 
integer xcoors 
integer ycoors 
integer n 

integer function cfpolyline(xcoors, ycoors, n) 
integer xcoors 
integer ycoors 
integer n 

integer function cfpolylnbundix(index) 
integer index 


integer function cfpolymarker(xcoors, ycoors, n) 
integer xcoors 
integer ycoors 
integer n 

integer function cfpolymkbundix(index) 
integer index 

integer function cfppolyline(xcoors, ycoors, n, flag) 
Integer flag 


integer function cfqasfs(n, num, vals) 
integer n 
integer num(*) 
integer vals(*) 


integer function cfqcellarr(px, qx, 
integer px, py 

integer qx, qy 

integer rx. ry 

Integer dx, dy 

integer colorind(*) 


fx, py, qy, ry, dx, dy, colorind) 


integer function cfqdevbtiqj (name, map) 
integer name, map 


integer function cfqdevclass(output, input) 
integer output, input 

integer function cfqdevld(name, devid, stringlen) 
integer name 
character*(*) devid 
integer stringlen 
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Integer function cfqflareaatts(style, vis, hindex, pindex, bindex, 

1 pstylo, pwidth, pcolor) 

integer style, vis, hindex, pindex 

integer bindex 

integer pstyle 

real pwidth 

integer pcolor 

integer function cfqinpcaps(valid, numval, numstrk, numchoice, 

1 numstr, numtrig, evqueue, asynch, coordmap, tracking, 

2 pronpt, acknowledgement, trigman) 

Integer valid 

integer numval 
integer numstrk 
integer numchoice 
integer numstr 
integer nximtrig 
integer evqueue 
integer asynch 
integer coordmap 
integer tracking 
integer pron^jt 
integer acknowledgement 
integer trigman 

integer function cfqlidcaps(devclass, devnum, valid, sanple, 

1 change, numassoc, trigassoc, prosit, acknowledgement, 

2 echo, classdep, stringlen, state) 
integer devclass 

integer devnum 
integer valid 
integer san^jle 
integer change 
integer numassoc 
integer trigassoc(*) 

Integer pronpt 
integer acknowledgement 
integer eoho(*) 
character*(*) classdep 
integer stringlen 
integer state(*) 
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integer function cfqlldstatelis(devclass, devnum, valid, niimloc, 

1 numval, numstrk, numchoice, numstr, numtrig, eventqueue, 

2 asynch, coordmap, echo, tracking, pronpt, acknowledgement, 

3 triggermanlpulatlon) 


integer 

devclass 

integer 

devnum 

integer 

valid 

integer 

numloc 

integer 

ntimval 

integer 

numstrk 

integer 

numcholce 

integer 

numstr 

integer 

nximtrlg 

integer 

eventqueue 

integer 

asynch 

integer 

coordmap 

integer 

echo 

integer 

tracking 

integer 

pronpt 

integer 

acknowledgement 

integer 

triggermanipu1ation 



Integer function cfglnatts(style, width, color, index) 
integer style 
real width 

integer color, index 

integer function cfgmkatts(type, size, color, index) 
Integer typo 
real size 

integer color, index 



integer function cfqoutcap(first, last, list) 
integer first, last 
character*(*) list 

integer function cfqoutfunset(level, support) 
integer level 
integer support 


integer function cfqpatatts(cindex, row, column, colorlls, x, y, dx, dy) 

Integer function cfqphyscsys(name, xbase, ybase, xext, yext, xunits, yunits) 
integer name 
integer xbase, ybase 
integer xext, yext 
real xunits, yunits 



G-16 


Revision A of 15 May 1985 





SunCGI Reference Manual 


Using SunCGI with Fortran-77 Programs 



Integer function cfqtext(fontset. Index, cfont, prec, efac, space, 

1 color, hgt, bx, by, ux, uy, path, hallgn, valign, hfac, cfac) 

integer fontset, index, cfont, prec 
real efac, space 

integer color, hgt 

real bx, by, ux, uy 

integer path, halign, valign 
real hfac, cfac 

integer function cfqtextext(string, stringlen, nextchar, 

1 conx, cony, llpx, llpy, ulpx, ulpy, urpx, urpy) 

character *(*) string 
character *(*) nextchar 
integer stringlen 

integer conx 

integer cony 

integer 1Ipx 

Integer 1Ipy 

integer ulpx 

Integer ulpy 

Integer urpx 

Integer urpy 

integer function cfqtrigcaps(trigger, valid, change, n, class, 

1 assoc, numassoc, maxassoc, pron^t, acknowledgement, 

1 name, namelen, description, desclen) 

integer trigger 

integer valid 

integer change 

integer n 

integer class 

integer assoc (*) 

integer numassoc 

integer maxassoc 

integer pron^jt 

integer acknowledgement 
character*(*) name 
integer namelen 

character*(*) description 
integer desclen 

integer function cfqtrlgstate(trigger, valid, state, n, class, assoc) 
integer trigger 

integer valid 

integer state 

integer n 

integer class (*) 

integer assoc(*) 

integer function cfqvdctype(type) 
integer 'type 
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integer function cfrectangle(xbot, ybot, xtop, ytop) 
integer xbot, ybot, xtop. ytop 


integer function cfrelldev(dovclass, devnum) 
integer devclass 
integer devnum 

integer function cfreqinp(devclass, devnum, timeout, valid, 
1 trigger, x, y, xlist, ylist, n, val, choice, string 


integer 

devclass 

integer 

devnum 

integer 

timeout 

integer 

valid 

integer 

X, y 

Integer 

xlist (*) 

integer 

ylist (*) 

integer 

n 

real 

val 

integer 

choice 

character 

*(*) string 

integer 

stringlen 

integer 

trigger 


integer function cfrsttodefs(name) 
integer name 


integer function cfsan^jinp(devclass, devnum, valid, x, y, 
1 xlist, ylist, n, val, choice, string, stringlen) 


integer 

devclass 

integer 

devnum 

Integer 

valid 

integer 

X. y 

integer 

xlist (*) 

integer 

ylist (*) 

integer 

n 

real 

val 

Integer 

choice 

character 

*(*) string 

integer 

stringlen 


integer function'cfsaspsouflags(fval, fnum, n) 
integer fval(*), fnum(*), n 

integer function cfsdofatrigassoo(devclass, devnum) 
integer devclass 
Integer devnxun 


sanple, 

stringlen) 
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integer function cfsdrawmode(visibility, source, 
integer visibility 
integer source 
integer destination 
Integer combination 


destination, combination) 


integer function cfselectflushevenqu(devclass, devnum) 
integer devclass 
integer devnum 

integer function cfserrwarnmk(action) 
integer action 


integer function cfsgldrawmode(combination) 
integer combination 


integer function cfsinitval(devclass, devnum, x, y, xlist, ylist, n, 
1 val, choice, string, stringlen) 


integer 

devclass 

integer 

devnum 

integer 

X, y 

integer 

xlist (*) 

integer 

ylist (*) 

integer 

n 

real 

val 

Integer 

choice 

character*(*) string 

integer 

stringlen 


integer function cfsupsig(sig_function) 
integer sig_function 

external sig_functlon 


integer function cfsvalrange(devnum, mn, mx) 
integer devnum 
real mn, mx 


integer function cftext(x, y, string, stringlen) 
Integer x 
integer y 
character*(*) string 
Integer stringlen 



Integer function cftextalign(halign, valign, hcalind, vcalind) 
integer halign 
integer valign 
real hcalind, vcalind 
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integer function cftextbundix(index) 
integer index 

integer function cftextcolor(index) 
integer index 

integer function cftextfontix(index) 
integer index 

Integer function cftextprec(ttyp) 
integer ttyp 

integer function cfvdcext(xbot, ybot, xtop, ytop) 
integer xbot, ybot, xtop, ytop 



integer function cfvdmtext(x, y, flag, string, stringlen) 
integer x 
integer y 
integer flag 
character*(*) string 
integer stringlen 


integer function vqdrawmode(visibility, source, destination, combination) 
integer visibility 
integer source 
integer destination 
Integer combination 



integer function vqfplxarr(px, py, m, n, colorind) 
integer px, py 
integer m, n 
integer colorind(*) 
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Cqasfs, 4-24 
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Cqevque, 5-15 
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Cqoutfunset, 2-9 
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Cqpixarr, 3-16 
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Cqtextext, 3-12 

Cqtrigcaps, 2-12 
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Cqvdctype, 2-9 

Crectangle, 3-5 

Crelidev, 5-4 
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Csaspsouf lags, 4-2 
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Cserrwarnmk, 2-19 
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Csupsig, 2-20 
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Ctext, 3-10 
Ctextalign, 4-19 
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Ctextprec, 4-14 
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hard_reset, 2-17 
hatch, 4-10 
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device_viewport, 2-16 
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line attributes, 4-4 thru 4-6 
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Clnvidthspecmode, 4-5 
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llne_width, 4-6 
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logical input device, 1-4 
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marker_color, 4-8 
marker_size, 4-8 

marker_slze_specifloatlon_moda, 4-7 
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measure, 1-4, 5-1, 5-1 
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negotiation functions, 1-3 
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open_cgl_pw, F-1 
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open_vws, 2-3 
option sets, 1-1 
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output primitive errors, D-5 (Art* D-6 
output primitives, 1-1, 1-3, 3-1 (An* 3-18, A-2 
append_text, 3-11 
bitblt_pattern_array, 3-14 
bitblt_patterned_source_array, 3-14 
bitblt_source_array, 3-13 
Captext, 3-11 
Cbtblpatarr, 3-14 
Cbtblpatsouarr, 3-14 
Cbtblsouarr, 3-13 
Ccellarr, 3-12 
Cciroarccent, 3-6 
Ccircarccentcl, 3-7 
Ccircarcthree, 3-8 
Ccircarcthreecl, 3-9 
Cclrcle, 3-6 
Cdpolyllne, 3-2 
cell_array, 3-12 
Celliparc, 3-9 
Celllparccl, 3-10 
Cell ipse, 3-9 
circle, 3-6 

circular_aro_3pt, 3-8 

circular_arc_3pt^close, 3-9 

circular_arc_center, 3-6 

clrcular_arc«center_oloso, 3-7 

conical, 3*1, 3-6 (An* 3-10 

Cplxarr, 3-13 

Cpolygon, 3-3 

Cpolyline, 3-2 

Cpolymarker, 3-3 

Cppolygon, 3-4 

Cqbtblallgn, 3-16 

Cqcellarr, 3-15 

Cqdevbtnp, 3-16 

Cqdrawmode, 3-18 

Cqpixarr, 3-16 

Cqtextext, 3-12 


output primitives, eonlinueJ 
Crectangle, 3-5 
Csdrawmode, 3-17 
Csgldrawmode, 3-18 
Ctext, 3-10 
Cvdmtext, 3-11 
disjolnt_polylino, 3-2 
drawing modes, 3-17 tAr« 3-18 
ellipse, 3-9 
elliptical_arc, 3-9 
olliptlcal_arc_close, 3-10 
geometrical, 3-1 (An* 3-10 
inquire_bitblt_alignments, 3-16 
lriquire_col l_array, 3-15 
inquire_dovico_bitmap, 3-16 
lnquiro_drawing_mode, 3-18 
inqulre_pixel_array, 3-16 
inqulre_text_extent, 3-12 
partlal_polygon, 34 
pixel_array, 313 
polygon, 33 
polygonal, 3-1, 31 (An* 38 
polyline, 32 
polymarker, 33 
raster, 310 (Art* 317 
rectangle, 35 
set_drawing_mode, 317 
set_global_drawing_mode, 318, 318 
text, 310 
vdm_text, 311 
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partial^polygon, 34 
pattern, 4-10 

reference point, 4-12 
pattern attributes, 4-10 (Art* 4-12 
Chatchix, 4-10 
Cpatix, 4-11 
Cpatrefpt, 4-11 
Cpatsize, 4-12 
Cpattable, 4-11 
hatch_lndex, 4-10 
pattern_index, 4-11 
pattern_reference_point, 4-11 
patterrusize, 4-12 
pattern_table, 4-11 
pattern_index, 4-11 
pattern_referenco^oint, 4-11 
pattern's Ize, 4-12 
pattern_table, 4-11 
perimeter 

endstyle, 4-13 

perimeter attributes, 4-12 (An* 4-14 
Cperimeolor, 4-13 
Cperimtype, 4-12 
Cperimwidth, 4-13 
Cperimwidthspecmode, 4-13 
perlineter_color, 4-13 
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perimeter attributes, continued 
perlmeter_typo, 4-12 
perimet:er_wldth, 4-13 
perimeter_width^speclfication_mode, 
4-13 

perimeter visibility, 4-9 
perinieter_color, 4-13 
periineter_type, 4-12 
perimeter_wldth, 4-13 

per imeter_wldth_speci f icat ion_jiiodo, 

4-13 

pie chart, 3-7 
pixel_array, 3-13, 3-13 
pixwins with CGI, F-1 thru F-5 
example, F-5 
functions, F-3 thru F-4 
using cgipw, F-2 
point 

drawing a, 3-6 
polygon, 3-3 

with holes, 3-4 
with undrawn edge(3), 3-4 
polygonal primitives, 3 - 1 , 3-1 thru 3-6 
polyline, 3-2 

polyline_bundle_index, 4-4 
polymarker, 3-3 
polymarker attributes, 4-6 thru 4-8 
Cmkcolor, 4-8 
Cmksize, 4-8 
Cmksizespecmode, 4-7 
Cmktype, 4-7 
Cpolymkbundix, 4-7 
marker_color, 4-8 
iDarker_size, 4-8 

marker _size_specification_mode, 4- 
7 

marker_typo, 4-7 
polymarker_bundle_index, 4-7 
polymarker_bundle_index,4-7 
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raster primitives, 3 - 1 , 3-10 thru 3-17 
rectangle, 3-5 
release_input_device, 5-4 
request register, 5-10, 5-11 
request_input, 5-11 
reset_to_defaults, 2-18 
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saiq3le_lnput, 5-10 
screen space, 1-3, 1-3, 2-13, 2-20 
definition, 2-16 

selective_£lush_of_event_queue, 5-5 
set_aspect_source_f lags, 4-2 
set_do fau1t_trigger_associations, 5-6 
set_draving_mode, 3-17 


set_error_warning_jBask, 2-19 
set_global_drawlng_mode, 3-18, 3-18 
set_lnitial_valuo, 5-7 
set_up_sigwinch, 2-20 
set_valuator_range, 5-7 
SIGWINCH, 1-3, 2-20 
solid object attributes, 4-8 thru 4-14 
Cflareabundlx, 4-9 
Cflcolor, 4-10 
Cintstyle, 4-9 

fill_area_bundle_index, 4-9 
flll_color, 4-10 
interior_style, 4-9 
specified device, 2-11 
state errors, D-1 thru'D-2 
status inquiries, 5-13 thru 5-15 
Sun Workstation, 2-7 
SunCGI, 1-1 

with window system, 2-20 
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text attributes, 4-14 thru 4-20 
Ccharexpfac, 4-16 
Ccharheight, 4-17 
Ccharordentation, 4-18 
Ccharpath, 4-18 
Ccharsetix, 4-15 
Ccharspacing, 4-16 
Cfixedfont, 4-17 

character_expansion_factor, 4-16 
character_height, 4-17 
character_orientation, 4-18 
character_path, 4-18 
character_set_index, 4-15 
character_spaclng, 4-16 
Ctextalign, 4-19 
Ctextbundix, 4-14 
Ctextcolor, 4-17 
Ctextfontix, 4-15 
Ctextprec, 4-14 
fixed_font, 4-17 
text_alignment, 4-19 
text_bundle_index, 4-14 
text_color, 4-17 
text_font_index, 4-15 
text_precislon, 4-14 
text precision, 3-11 

detailed definition, 4-14 
text, 3-10 

appended, 3-11 
text_aligninent, 4-19 
text, 3-10 

text_bundle_lndex, 4-14 
text_color, 4-17 
text_font_lndex, 4-15 
text^reclsion, 4-14 
textured line, 4-5 
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track, 5-1, 5-8, 5-9 
track_off, 5-9 
track_on, 5-8 
tracking, 5-8 thru 5-9 
trigger, 1-4, 2-10, 5-1, 5-6 
activation, 5-1 
Trigger 

Capabilities, 2-12 
trigger 

interaction with stroke device, 5-6 
status, 5-13 

type definitions, C-1 thru C-9 

u 

unsupported CGI functions, B-1 thru B-2 
using SunCGI, 1-2 

V 

VDC Space, 1-3, 1-3, 2-13, 2-13, 2-20 
vdc_extent, 2-14 
vdin_text, 3-11 
view surface, 2-1 

clear control, 2-19 
clearing, 2-18 
default states, 2-5 
view surface control, 2-13 thru 2-19 
Cclipind, 2-16 
Ccliprect, 2-17 
Cclrcont, 2-19 
Cclrvws, 2-18 
Cdewpt, 2-16 
Chardrst, 2-17 
clear_control, 2-19 
clear_view_surface, 2-18 
cllp_indicator, 2-16 
clip_rectangle, 2-17 
Crsttodefs, 2-18 
Cserrwarnnik, 2-19 
Cvdcext, 2-14 
dGvlce_viewport, 2-16 
hard_reset, 2-17 
reset_to_dGfaults, 2-18 
set_error_warning_mask, 2-19 
vdc_extent, 2-14 
view surfaces, 2-5 
active, 1-3 
initializing, 2-3 
multiple, 1-3, 2-3 
visual errors 

possible causes, D-8 thru D-10 

w 

window system 
Csupsig, 2-20 
set_up_slgwinch, 2-20 
using SunCGI with, 2-20 
windows 


windows, continued 
nonretained, 2-4 
retained, 2-4 

world coordinates (see VDC Space), 2-13 
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X3H3, 1-1 
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